Describe the surface once, not in every field

crates/imcp2-core/src/identities.rs

@@ -350,23 +350,16 @@ pub struct AccountInfo {
     pub last_used: Option<u64>,
 }
 
-/// Arguments for `get_app_principal`. Identify the app by its canonical derivation
-/// origin (`derivation_origin`), obtained from `open_app` / `resolve_app`.
+/// Arguments for `get_app_principal`.
 #[derive(Debug, Deserialize, schemars::JsonSchema)]
 pub struct GetPrincipalArgs {
-    /// The exact canonical origin Internet Identity uses to derive this app's
-    /// principal — NOT necessarily the website's visible URL. For an app that
-    /// pins a custom derivation origin (via `derivationOrigin` +
-    /// `/.well-known/ii-alternative-origins`), pass that canonical origin here
-    /// (e.g. "https://<frontend-canister>.icp0.io"). Do NOT infer it from an
-    /// alternativeOrigins list, and do NOT pass a raw website URL — get the
-    /// derivation origin from open_app / resolve_app (which resolve an app name or
-    /// URL to it under the guessed-domain gate) and reuse it. Accepts the legacy
-    /// name `domain`. Required — this tool always acts as an app account.
+    /// The app's derivation origin, from open_app. This is the origin Internet
+    /// Identity derives the principal from, which is not always the app's website URL, and
+    /// never an alternative-origins entry.
     #[serde(alias = "domain")]
     pub derivation_origin: String,
-    /// Which of your accounts to resolve, by account name (see list_app_accounts).
-    /// Omit to use that app's default account.
+    /// Which of the user's accounts to resolve, by name (see list_app_accounts). Omit for the
+    /// app's default account.
     #[serde(default)]
     pub account: Option<String>,
 }
@@ -375,41 +368,32 @@ pub struct GetPrincipalArgs {
 #[derive(Debug, Serialize, schemars::JsonSchema)]
 pub struct PrincipalOutput {
     /// The effective Internet Identity derivation origin the principal was
-    /// derived for (after canonicalization). Compare against `requested` to spot
-    /// an origin mismatch.
+    /// derived for. Compare against `requested` to spot an origin mismatch.
     pub derived_for_origin: String,
-    /// Exactly what you supplied as `derivation_origin`, echoed so a mismatch with
-    /// `derived_for_origin` (from canonicalization) is immediately visible.
+    /// Exactly what you supplied as `derivation_origin`.
     pub requested: String,
-    /// How `derived_for_origin` was determined — always "explicit" here, since this
-    /// tool takes the canonical derivation origin directly. (The "declared" /
-    /// "known" / "app_url_default" sources are reported by the resolver tools
-    /// open_app / resolve_app, which turn a URL into a derivation origin.)
+    /// How `derived_for_origin` was determined.
     pub derivation_origin_source: String,
     /// The account name resolved, or null for the app's default account.
     pub account: Option<String>,
     /// The principal you act as at that app.
     pub principal: String,
-    /// True if this Internet Identity session is query-only (canister management
-    /// is unavailable until reconnected under "Actions & questions").
+    /// True if this session is query-only, so state-changing calls are rejected by the
+    /// network. False also covers a session whose access level is not known.
     pub read_only: bool,
 }
 
-/// Arguments for `list_app_accounts`. Identify the app by its canonical derivation
-/// origin (`derivation_origin`), obtained from `open_app` / `resolve_app`.
+/// Arguments for `list_app_accounts`.
 #[derive(Debug, Deserialize, schemars::JsonSchema)]
 pub struct ListAccountsArgs {
-    /// The exact canonical Internet Identity derivation origin (NOT necessarily the
-    /// visible URL). Do NOT pass a raw website URL — get the derivation origin from
-    /// open_app / resolve_app (which resolve an app name or URL to it under the
-    /// guessed-domain gate) and reuse it. Accepts the legacy name `domain`. Required
-    /// to identify the app.
+    /// The app's derivation origin, from open_app. This is the origin Internet
+    /// Identity derives the principal from, which is not always the app's website URL, and
+    /// never an alternative-origins entry.
     #[serde(alias = "domain")]
     pub derivation_origin: String,
 }
 
-/// One account in the `list_app_accounts` MCP output (a serialization mirror of
-/// [`AccountInfo`]).
+/// One account in the `list_app_accounts` MCP output.
 #[derive(Debug, Serialize, schemars::JsonSchema)]
 pub struct AccountEntry {
     /// The user-given account name, or null for the default account.
@@ -435,67 +419,14 @@ impl From<&AccountInfo> for AccountEntry {
 pub struct AccountsOutput {
     /// The effective Internet Identity derivation origin the accounts belong to.
     pub derived_for_origin: String,
-    /// Exactly what you supplied as `derivation_origin`, echoed so a mismatch with
-    /// `derived_for_origin` (from canonicalization) is immediately visible.
+    /// Exactly what you supplied as `derivation_origin`.
     pub requested: String,
-    /// How `derived_for_origin` was determined — always "explicit" here, since this
-    /// tool takes the canonical derivation origin directly. (The "declared" /
-    /// "known" / "app_url_default" sources are reported by open_app / resolve_app.)
+    /// How `derived_for_origin` was determined.
     pub derivation_origin_source: String,
     /// The user's accounts at that origin (empty if none).
     pub accounts: Vec<AccountEntry>,
 }
 
-/// Arguments for `resolve_app`.
-#[derive(Debug, Deserialize, schemars::JsonSchema)]
-pub struct ResolveAppArgs {
-    /// The application's URL, e.g. "https://opencloud.org". When the derivation
-    /// origin has to be assumed from this URL, the origin is checked for
-    /// Internet-Computer evidence (a gateway `x-ic-canister-id`) and the call is
-    /// refused without it — so a lookalike domain that is not an IC app does not
-    /// resolve. `open_app` turns an app name into this URL.
-    pub app_url: String,
-}
-
-/// Structured output of `resolve_app`.
-#[derive(Debug, Serialize, schemars::JsonSchema)]
-pub struct ResolveAppOutput {
-    /// The normalized application origin of `app_url`.
-    pub application_origin: String,
-    /// The Internet Identity derivation origin to use for this app — pass this
-    /// as `derivation_origin` to the identity tools.
-    pub derivation_origin: String,
-    /// How `derivation_origin` was determined: "declared" (the app declared it,
-    /// in /.well-known/ii-derivation-origin or in the legacy /.well-known/ic-app.json
-    /// — authoritative), "known" (from the connector's
-    /// built-in registry of well-known custom-derivation-origin apps, used only
-    /// when the app declares none), or "app_url_default" (assumed to equal the
-    /// application origin — correct only if the app has no custom derivation
-    /// origin, which this connector cannot verify).
-    pub derivation_origin_source: String,
-    /// Origins the resolved DERIVATION origin's `/.well-known/ii-alternative-origins`
-    /// permits to derive against it — that origin is where the list is authoritative,
-    /// and where this one was read. Read best-effort and reported as a list, so an
-    /// empty one means "none were read", not "none exist": a fetch, HTTP, parse, or
-    /// origin-validation failure yields an empty list, and at most 100 valid entries
-    /// are kept. Informational only either way: it is the INVERSE of "which
-    /// derivation origin the app uses", so the derivation origin does not follow from
-    /// it.
-    pub alternative_origins: Vec<String>,
-    /// Whether the application origin showed evidence of being served from the
-    /// Internet Computer (the gateway's `x-ic-canister-id` header). Only probed
-    /// when `derivation_origin_source` is "app_url_default" (and then always
-    /// true here — an origin with NO IC evidence is refused instead of resolved);
-    /// null when the probe wasn't needed (declared/known origins).
-    pub application_is_ic: Option<bool>,
-    /// A human note, e.g. flagging that the derivation origin was assumed.
-    /// This tool deliberately does NOT return a principal: it resolves the
-    /// derivation origin only, since the caller hasn't chosen an account. Get the
-    /// principal with `get_app_principal` (or `list_app_accounts`) for a specific
-    /// account, passing this `derivation_origin`.
-    pub note: Option<String>,
-}
-
 #[derive(Clone)]
 pub struct Identities {
     /// The II instance every session in this store is registered against.

crates/imcp2-core/src/management.rs

@@ -86,7 +86,7 @@ pub struct UpdateSettingsArgs {
     /// Freezing threshold in seconds.
     #[serde(default)]
     pub freezing_threshold: Option<u64>,
-    /// Reserved-cycles limit.
+    /// Reserved-cycles limit, in cycles.
     #[serde(default)]
     pub reserved_cycles_limit: Option<u64>,
     /// Wasm heap memory limit in bytes.