Proof Holdings

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries most of the burden and delivers real context: the member is 'pending', the Telegram chat id is bound later via a deep link, and the tool needs an authenticated Proof account (with a note that start_login does NOT unlock it). It does not state rate limits or what happens to duplicate members, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short paragraphs, front-loaded with the action before the follow-up workflow and the access note. Every sentence carries information; it is slightly longer than strictly necessary but no sentence is waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with no output schema, it covers authentication, the pending-state lifecycle, and the next-tool handoff. What remains uncovered (duplicate handling, error/return behavior) is minor but leaves a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, name and whatsapp_phone with patterns and lengths; baseline is 3. The description adds only the temporal semantics of the phone ('pre-declared') and the name binding, which is useful but marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb, resource and scope ('add a pending member to a Circle by name, with an optional pre-declared WhatsApp phone'), and clarifies the member-vs-channel distinction against the sibling add_circle_member_channel family. An agent knows exactly what object is being created without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit sequencing ('after adding a member, call invite_circle_member to mint the single-use enrollment link') and states the authentication prerequisite. It stops short of naming when NOT to use it versus alternatives such as add_circle_member_channel or create_circle_member_drill, so it falls just below a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=false and destructiveHint=false already declared, the description adds meaningful behavior beyond annotations: the 409 response when the channel type already exists, server-side per-channel format validation, and the authentication gate. It does not describe what the successful response contains, but the disclosure of error and auth behavior is strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then error behavior, then access requirements. Two sentences are efficient, though the ACCESS block is slightly verbose for a 4-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description covers the failure mode (409 duplicate channel) and the auth requirement, which are the key things an agent needs to call this correctly. Only the success return shape is left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters and the enum. The description restates the identifier format and adds that validation happens server-side, which is marginal added value over the schema rather than new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Declare a channel for a Circle member'), so the agent knows exactly what operation is performed. It does not explicitly contrast with the sibling add_circle_member or the remove/list channel tools, but the resource is narrow enough that confusion is unlikely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete access prerequisite (needs a Proof account, authenticate first, and start_login does NOT open this tool), which is useful operational guidance. However, it says nothing about when to prefer this tool over alternatives or what conditions make it appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only declare readOnlyHint=false and destructiveHint=false; the description goes beyond that by disclosing the account requirement and the full auth/session-then-retry flow, which is exactly the kind of context that cannot be inferred from the schema. It still omits the resulting state — whether the domain lands unverified awaiting a separate verification step, and whether re-adding an existing domain errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in the first sentence, with optional parameters immediately after and the auth prerequisite separated into its own labeled ACCESS block. The auth paragraph is slightly verbose (naming both a UI path and a tool fallback), but every sentence conveys actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with annotations covering the safety profile and no output schema, the description covers the prerequisite and parameters but leaves the post-call lifecycle unexplained — what the add returns, and which sibling (start_domain_verification, verify_domain, connect_dns_provider) an agent should call next. That next-step linkage is the main gap given the dense domain-verification sibling set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the enum values for verification_method are enumerated in the schema, so the structured data already carries the parameter burden. The description adds only the relatively weak signal that email-sending intent and verification method are optional (the schema's required list already shows this), which is baseline-level value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Add a new domain') and adds the purpose clause 'to verify ownership', so an agent knows exactly what is being created. It does not, however, distinguish itself from the many verification siblings (start_domain_verification, verify_domain, check_domain_verification) that also operate on domains, so an agent must infer which one actually performs the add step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS block gives concrete usage context: a Proof account is required, the client must be authenticated (via /mcp or start_login), and the tool must be re-invoked after a session opens. That is a clear precondition and sequence. What is missing is routing guidance — nothing says whether verification happens here or requires a separate start_domain_verification/verify_domain call, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partially covered. The description adds genuinely useful context beyond that: credentials will be exposed in the AI conversation context, and the tool requires an authenticated session established via a second call. It does not clarify what the 'destructive' aspect means (e.g., whether existing providers are replaced).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action in the first sentence, followed by the credential-sensitivity warning and then the access prerequisites. Every sentence earns its place; the only mild redundancy is restating the credential warning and auth flow at some length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with destructive annotations and no output schema, the description covers the prerequisites and a notable security caveat (credential visibility). It leaves open what the destructive side effect is and what happens to previously configured providers, which is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with id, provider, and credentials each documented in the schema, so the schema carries the parameter burden. The description adds no format or syntax detail beyond what is already there. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus a meaningful qualifier: 'Add an additional DNS provider for verification to an already-verified domain.' That scope constraint distinguishes it from the broader set of connect_*/create_dns_credential siblings, though no sibling is named explicitly. Clear enough that an agent knows what the tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real preconditions: the domain must already be verified, a Proof account is required, and it spells out the auth flow (authenticate via /mcp or start_login, then re-call). It does not explicitly contrast with alternatives like connect_dns_provider or create_dns_credential, so it stops short of a 5, but the when-to-use context is concrete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds the creator-only authorization constraint and the pending-state requirement, which are genuinely useful behavioral details not in annotations. It does not however say whether cancellation is reversible or what happens to already-collected proofs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and creator constraint are front-loaded in the first two sentences, which is ideal. The third paragraph is somewhat verbose authentication boilerplate that could be terser, but it is properly relegated to the end.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive tool with no output schema, the description covers the key agent needs: what it does, who may call it, and how to authenticate. Only the post-cancellation state and reversibility are left unstated, and these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'id' parameter is fully documented in-schema as 'Verification request ID to cancel.' The description adds nothing beyond the schema about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (cancel) and resource (pending verification request), and adds a crucial distinguishing constraint: 'Only the creator can cancel.' Among many cancel/revoke siblings (cancel_verification_request, revoke_authorization, etc.) this scope and restriction make the tool's identity unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'only the creator can cancel' rule effectively tells the agent the precondition for use, which is useful guidance. However, it does not explain when to reach for this vs. the near-identical sibling cancel_verification_request, nor does it state the resulting state of the request after cancellation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is supplementary — and it does add real context: the pending-only gating rule and the Proof account authentication requirement. The client-specific /mcp authenticate aside is procedural noise rather than behavioral disclosure, but the gating rule is genuinely useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and precondition are front-loaded in two tight sentences. The ACCESS block is slightly verbose and client-specific, but it is short and separated from the primary function statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive mutation with annotations covering the safety profile and no output schema, the description supplies the one thing the structured fields lack: the pending-only precondition and auth requirement. Nothing critical is missing, though the failure mode for a non-pending ID is unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single clearly documented 'id' parameter, so the baseline is 3. The description adds no extra meaning about the ID (e.g. where to obtain it), but the schema already carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Cancel a pending verification request') and immediately narrows scope with a precondition. It does not, however, distinguish itself from the near-identical sibling cancel_user_request, leaving that routing decision to the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use condition ('Only pending requests can be cancelled') and explicit access prerequisites, including a warning that start_login does not grant access. It stops short of naming an alternative tool or stating what to do when the request is no longer pending.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable non-annotation context: it requires a Proof account and an authenticated session, with concrete steps ( /mcp authenticate or start_login). It does not describe what a negative result means or whether the check has side effects, but the auth disclosure is genuinely useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Core purpose and usage are front-loaded in the first sentence, with auth prerequisites separated into a clearly labeled ACCESS block. The auth prose is slightly verbose but earns its place for a tool that fails without a session.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only check with annotations covering safety and no output schema, the description supplies the missing prerequisite information (account and session requirements). Only the semantics of the boolean/result outcome are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single well-described `id` parameter, so the schema carries parameter meaning. The description adds nothing about the id's format or source beyond what the schema states; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: checks whether stored DNS credentials can access a domain. This distinguishes it from the many domain/verification siblings such as verify_domain_with_credentials and check_domain_verification, though it does not name an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use before triggering verification to confirm the credentials work" gives clear sequencing guidance relative to the verification flow. It provides no explicit when-not or named alternative, but the intended usage context is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read. The description adds real behavioral context beyond the annotation: the account requirement and the session/auth flow that must happen before the call succeeds. It does not describe return shape, but the safety profile is covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, purpose front-loaded and the access caveat clearly separated. Nothing is redundant, though the authentication aside is somewhat verbose relative to the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still conveys what the tool reports (sending setup status plus DNS record progress) and the prerequisite to get a result. For a single-parameter read-only status check this is close to complete, with only the exact return fields left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and there is only one parameter (id, 'Domain ID'), so the schema carries the parameter meaning. The description's phrase 'for a domain' corroborates but adds no syntax, format, or lookup detail beyond what the schema provides, making baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (check) and resource (email sending setup status for a domain) and adds scope detail (DNS record configuration progress). It is distinguishable from verification-oriented siblings like check_domain_verification or get_user_domain_verification_status, though it never names those neighbors explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains the access prerequisite (needs a Proof account, authenticate or use start_login then retry), which is genuinely useful context. However, it offers no guidance on when to prefer this over adjacent tools such as check_domain_credentials, check_domain_verification, or get_domain.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, which the description is consistent with: it discloses that the call triggers an outbound DNS/HTTP check rather than passively reading. It also flags the authentication prerequisite, which is real behavioral context beyond the annotations. No return payload shape or rate-limit info, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The behavioral sentence is front-loaded and wastes nothing. The ACCESS block is slightly verbose for what it conveys, but it is clearly separated and actionable rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter status-check with no output schema, the definition covers purpose, the network side effect, what is returned, and the auth prerequisite. An agent could call it correctly; only routing against sibling verification tools is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema coverage is 100%, so the schema already documents 'id' as the domain verification ID. The description adds nothing about the parameter's format or where to obtain it, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Check the status') and resource ('pending domain verification') and adds what the call actually does ('Triggers a DNS/HTTP check and returns the updated status'). It does not name or differentiate itself from close siblings such as verify_domain, get_domain, or start_domain_verification, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'pending' implies this is called after start_domain_verification or verify_domain, but no alternative is named and no when-not condition is given. The access block adds practical invocation guidance (account required, authenticate first), which is helpful but not selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations say readOnlyHint=false and destructiveHint=false, so the agent knows it mutates state harmlessly. The description adds real context beyond that: the tool requires an authenticated Proof account and describes the auth flow (/mcp Authenticate or start_login). It doesn't say whether the check is synchronous or requires polling, which is a gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The behavioral instruction is front-loaded and short; the auth paragraph is longer but earns its place by explaining a non-obvious prerequisite. Slightly verbose in the parenthetical CLI detail, but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should clarify what a check returns (pass/fail, or a result requiring a separate status call to get_user_domain_verification_status). It covers auth and timing but leaves the outcome/polling model unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single session_id parameter, so the schema already carries the semantics. The description adds nothing about the session_id's origin or format, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Trigger a check') and resource ('domain verification challenge'), which distinguishes it from read-only siblings like get_user_domain_verification_status. It stops short of explicitly naming which sibling to prefer, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear timing context: 'Call after placing DNS record or HTTP file.' It also states the precondition that a Proof account is required. It does not name alternative tools (e.g. get_user_domain_verification_status for polling results), so it falls short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds genuinely useful behavior context beyond that: the auth requirement and the /mcp or start_login flow. It omits what happens if the username is already taken, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, constraints follow, then access notes. Efficient overall, though the length/character constraints duplicate what the schema already states, which is mildly wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation with no output schema and annotations covering the safety profile, this covers purpose, constraints, and auth. Only minor omissions remain, such as conflict/failure behavior when a username is unavailable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter fully documents pattern, min/max length. The description's '3-30 characters, alphanumeric and underscores' repeats the schema verbatim rather than adding new meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Claim a unique username') scoped to the authenticated user's public profile. No sibling tool in the list does anything similar, so an agent can identify it immediately without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear prerequisite context: needs a Proof account, and either authenticate the client or sign in via start_login, then re-call this tool. This explains the preconditions for use well, but doesn't explicitly contrast with alternatives (e.g., update_profile's username handling).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag this as non-read-only and non-destructive, so the safety profile is partly covered. The description adds valuable behavioral context by requiring a Proof account and describing the auth sequence, but says nothing about failure modes (wrong/expired code), side effects of confirming, or whether the operation is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in one sentence, followed by a clearly labeled ACCESS block. The auth note is somewhat verbose with client-specific detail, but every sentence contributes actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a non-destructive mutation with annotations and no output schema, the description covers purpose, the prerequisite account/auth flow, and how to resume after sign-in. The remaining gap is what confirmation returns or how verification status changes, which is acceptable given the missing output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (id, code) are already documented in the schema. The description reinforces that the code comes from the corporate email but adds no syntax, format, or length detail beyond what the schema provides. Baseline 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (confirm) and resource (domain email verification) plus the mechanism (submitting the code sent to the corporate email address). It is clear what the tool does, though it does not explicitly name the closest siblings (submit_verification_code, check_domain_email_status) to help disambiguate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It supplies an explicit access precondition and workflow: authenticate the client or sign in via start_login, then call this tool again. This tells the agent when the tool is callable. It stops short of contrasting with the similarly named submit_verification_code, so it is not a full when-vs-alternative guide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds two things annotations cannot: a security disclosure that the API token is visible in the conversation context, and the authentication/session workflow needed to invoke the tool. It does not elaborate on what aspect is destructive, keeping it just short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, followed by the security warning and then the access block. Every sentence is functional; the access block is slightly long but directly actionable, so the size is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no output schema, the description covers the prerequisite account/session flow and the security implication of passing a token, which are the main invocation blockers. It stops short of mentioning post-connection state or error behavior, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (id, api_token) are fully documented in the schema. The description maps the token to a domain conceptually but adds no syntax, format, or permission detail beyond what the schema already states. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (connect), resource (Cloudflare API token), and scope (to a domain for DNS record management). The Cloudflare name distinguishes it from siblings connect_godaddy and connect_dns_provider without requiring schema inspection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS block gives clear prerequisites (Proof account) and two concrete paths to satisfy them, with a pointer to start_login and the session requirement. It does not explicitly say when to prefer this over connect_godaddy/connect_dns_provider, but the provider name in the description acts as the selector.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds meaningful context beyond that: credentials will be visible in the AI conversation context (a security caveat the agent needs) and the required auth flow. It does not explain what 'connecting' changes for the domain or reversibility, keeping it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded blocks: the action sentence with the credential-visibility warning, then the ACCESS note. Nothing is redundant, though the access block is slightly verbose relative to the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a 3-param mutation tool with a nested credentials object, no output schema, and destructiveHint, the description covers the essentials an agent needs: what it does, the auth precondition, and the credential-exposure caveat. Only the alternative-tool routing and post-connect effects are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so id, provider, and credentials are already documented in the schema. The description only adds the phrase 'provider-specific credentials,' which reinforces but does not extend schema meaning. Baseline 3 applies when the schema carries the parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('connect a generic DNS provider to a domain'), and the word 'generic' implicitly contrasts with sibling tools connect_cloudflare and connect_godaddy. It is clear what the tool does, though it never names the provider-specific alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides access prerequisites (needs a Proof account, authenticate via /mcp or start_login before calling again), which is useful operational guidance. However, it does not say when to use this generic connector versus connect_cloudflare/connect_godaddy or create_dns_credential, so the key selection decision is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new context: the security disclosure that 'the API key and secret will be visible in the AI conversation context' plus the authentication flow. It stops short of explaining what the destructive hint means in practice (e.g., whether existing DNS credentials or records are overwritten).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then a security note, then an actionable access block. Every element is useful, though the parenthetical CLI instructions make it slightly longer than a pure description needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a credential-binding tool with no output schema, the description covers purpose, the sensitive-data warning, and the authentication prerequisite well. It omits what happens on success/failure and whether an existing GoDaddy connection is replaced, which matters given the destructive annotation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with three self-documenting parameters (id, api_key, api_secret), so the schema already carries the semantics. The description adds no format, sourcing, or provenance detail for the credentials, giving baseline performance only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Connect'), resource ('GoDaddy API credentials'), target ('a domain'), and outcome ('automated DNS record management'). This is clearly distinguishable from siblings like connect_cloudflare, connect_dns_provider, and create_dns_credential, which an agent could otherwise confuse.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS block gives concrete preconditions and a recovery path ('needs a Proof account', '/mcp → Authenticate', or 'sign in with start_login ... then call this tool again'). It does not, however, contrast this tool against the other provider-connection or credential-creation siblings, so the agent must infer when GoDaddy-connect is correct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false and destructiveHint=false, but the description adds substantial context: public/no-API-key access, a deliberately uniform response that avoids a user-enumeration oracle, email channel sending nothing with email_sent=false/send_required=true, and JWT+refresh cookies being set on verified. This is far beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, response shape and the numbered agent workflow are front-loaded and well structured, and most sentences carry operational value. It is long and dense for a single tool, but the length is largely justified by the multi-step orchestration it must document.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description enumerates return fields (session id, channel instructions, deep_link, qr_code, qr_text, email_sent, send_required, sms_message) and explains the JWT/cookie outcome on verification. Combined with the full usage flow, an agent has everything needed to call and follow up correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents channel, email and phone_number, giving a baseline of 3. The description adds real meaning tied to the channel parameter — deep_link is populated only for telegram/whatsapp, empty for sms, and phone routing behavior — which helps the agent choose and interpret inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Create an account-bootstrap session for agent-driven onboarding') and immediately scopes it against siblings by naming send_account_email, render_auth_link and wait_for_account_creation as the follow-on calls. An agent can tell exactly what this does versus start_login, create_session or create_identity_challenge without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit numbered when-to-use workflow, including channel-specific routing (email → send_account_email, telegram/whatsapp → render_auth_link, sms → show sms_message), plus 'when-not' warnings (do not hand qr_text to a link renderer, do not invent an SMS number, render_auth_link will reject empty deep_link). Nothing about the decision path is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds critical non-obvious behavior: the secret is returned only once, it is exposed in conversation context, 2FA elevation is required, 403 signifies expired 2FA session, and profile_id is immutable after creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the operation and the one-time secret warning, then a compact auth/2FA section. Slightly long but every sentence carries a distinct operational fact; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param creation tool with no output schema, the description covers the one-time secret handling, 2FA prerequisite chain, failure recovery, and account/auth requirement. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already documented (each including the immutable profile_id note). The description restates the profile_id binding and branding effect but adds no syntax beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new API key') and immediately clarifies the key differentiator vs siblings like regenerate_api_key and revoke_api_key: the secret is returned only once. The profile_id binding behavior further distinguishes its effect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit prerequisites (2FA flow with the exact action_type 'api_key_create'), the ordered steps, the alternative tool names to call (start_2fa, get_2fa_status), and a 403 recovery path. This is rare, actionable when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=false and destructiveHint=false already indicating a non-destructive write, the description adds useful behavior: the authorization requires user approval, confirmations cannot be sent until approved, and authentication is required. It does not cover idempotency, rate limits, or what happens if an authorization already exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, followed by a compact explanation of approval workflow and a clearly separated ACCESS note. Every sentence contributes useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter create tool with full schema coverage and no output schema, the description covers purpose, workflow, and authentication prerequisites well. It could be stronger by describing the immediate return behavior or how to check approval status afterward, but the core invocation context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all 9 parameters, including formats, enums, defaults, and limits. The description adds only high-level context about sending confirmations via a specific channel and does not provide additional parameter-level syntax or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: 'Create a new authorization request.' It then explains what an authorization does and its approval workflow, making the tool's role clear relative to sibling tools such as revoke_authorization, list_authorizations, and get_authorization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the prerequisite context clearly: a Proof account is required, the client must be authenticated, and start_login does not open this tool. It also implicitly explains when to use it by saying authorizations must be approved before confirmations can be sent, though it does not explicitly compare against all alternative authorization or confirmation tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only flag readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that: the exact return payload, the auth requirement (Proof account plus client authentication), and the non-obvious client behavior that the user does not see tool results. This is exactly the behavioral disclosure annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return values, then action sequence, then the user-visibility caveat, then access. Dense and mostly waste-free, though the three-paragraph layout is longer than strictly necessary and the ACCESS block is somewhat bolted on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description fully compensates by explaining the returned fields, the polling follow-up, and the authentication prerequisite. Nothing an agent needs to invoke and sequence this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description usefully documents the return shape (deep_link, qr_code, qr_text) even though there are no inputs to disambiguate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Create a Telegram chat ID discovery token') and immediately states what it returns (deep_link, qr_code, qr_text) and why (reveals the user's chat ID for HITL config). An agent can distinguish this from siblings like create_hitl or poll_chat_id_discovery without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit chain: pass deep_link to render_auth_link, never feed qr_text to a link renderer, then poll poll_chat_id_discovery until chat_id appears, then use that chat_id in a HITL config. It names both the downstream tool and the follow-up tool, plus the pitfall to avoid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=false and destructiveHint=false, so the description usefully adds the auth requirement/flow and the side effect that declared channels are stored for later enrollment. It does not cover failure modes, rate limits, or idempotency, and the owner_name naming behavior is largely mirrored in the schema, so it stops short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what a Circle is and what the tool does, then a compact 'Agent usage' sequencing block, then access prerequisites. No filler sentences; each line adds routing or prerequisite information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should ideally say what the call returns (e.g. a circle id needed for subsequent add/invite calls); it only gestures at the follow-up steps without identifying the returned handle. Otherwise it is complete for a 5-param create tool with full schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by framing `members` as optional seeding and explaining that declared channels are persisted for enrollment, and it flags `profile_id` semantics (bind for branded messages). It does not clarify whether seeded members auto-receive invites, which would push it higher.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Create) and resource (Circle), defines the concept inline (a named group of trusted contacts) and anchors it to the product domain (Proof-Me, Approvals-on-Circle). It is clearly distinguishable from siblings like add_circle_member and invite_circle_member, which are named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit sequence: create, then add_circle_member (or seed here), then invite_circle_member to mint the enrollment link. It also states the prerequisite (Proof account, authenticate via /mcp) and an exclusion — start_login does NOT open this tool, which prevents the obvious wrong alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false; the description is consistent, describing a non-destructive write that fires a real cross-channel identity challenge with a 'scheduled-safety-check' label. It also adds useful operational detail the annotations lack — the Proof account requirement and that start_login does NOT unlock this tool — which is genuinely helpful auth context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action in the first clause, then adds the complement/scope context and access instructions. Slightly dense with parenthetical framing ('the account owner practices confirming'), but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter non-destructive mutation with a fully documented schema and no output schema, the description covers purpose, prerequisites, and auth flow adequately. It omits what the drill returns to the caller or how the member experiences it, which is a minor gap given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both `id` (Circle ID) and `member_id` documented including their 24-hex-char patterns. The description adds no additional parameter semantics beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Fire an on-demand Proof-Me drill against one enrolled member.' It clarifies the scope (one member, cross-channel identity challenge) and situates the tool as the manual complement to the automated daily/monthly sweeps, which distinguishes it from bulk verification tools. It doesn't name a specific sibling by name, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: on-demand manual drill vs the automated daily drill and monthly reinforcement sweeps, plus an explicit prerequisite (needs a Proof account and client authentication). It provides no exclusion rules or named alternatives among the many verification/challenge siblings, so 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only tell the agent this is not read-only and not destructive. The description goes far beyond: mandatory keypair encryption, specific 400 error codes (message_not_encrypted, message_key_mismatch, envelope_missing_approvers), the v1 vs v2 recipient rules, AAD binding, and the required account authentication step. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and routing, then encryption rules in a scannable bullet list. It is long, and the plaintext-refusal rule is stated both in the description and the `message` schema field, so there is mild redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description supplies everything needed: auth prerequisite, failure modes with codes, envelope construction path, and how to observe the result (poll or generate a link). Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning for `message` by explaining the v1/v2 envelope decision rule (owner-only vs enrolled approvers) and the SDK helpers to build it. hitl_id and proof_expiry_days gain little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a HITL confirmation request') and immediately describes the mechanism: an approval request sent to the channels on the referenced HITL config, with 'first response wins' semantics. It is clearly distinguishable from siblings like get_confirmation, list_confirmations, and create_hitl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly covers when-to-use and the routing logic: hitl_id must be authorized first, and on a 403/'not authorized' the agent should call request_hitl_authorization and wait. It also names the follow-up alternatives — get_confirmation for polling and get_confirmation_approval_link for a fresh link.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description carries the rest: it discloses that each mint is a billable proof, that an over-long lifetime is rejected rather than truncated, that the result carries both the publishable token and the DERIVED effective_status/is_valid, and that this pair is stable across verbs. These are non-obvious operational traits an agent must know before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and its constraints are front-loaded, and the ACCESS block is clearly separated at the end. The middle sentences ('nothing more; it says nothing about the artifact or the business behind it') are somewhat discursive for a tool description, but they do carry semantic boundaries rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description explains the return payload (publishable token plus derived effective_status/is_valid). Combined with auth requirements, billing implications, lifetime rejection behavior, and nested-object parameter meaning, an agent has everything needed to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by framing scope as 'capability scopes' tied to the delegation's authorization semantics and by clarifying that the control proof belongs to the caller's active domain control proof. The explicit invalid_scope note partially duplicates the scope schema description, so the added value is real but moderate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb+resource ('Create a delegation (Proof of Delegation)') and immediately defines the resulting semantic: a control-proven domain authorizes a typed url/purl artifact for capability scopes and returns a signed token. It also scopes the meaning ('the domain's controller authorized this artifact — nothing more'), which prevents an agent from over-reading the artifact. It references the sibling list/get tools whose output shape it shares, giving light disambiguation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Prerequisites are explicit and actionable: a Proof account is required, the client must be authenticated, and the description warns that start_login does not open this tool. It also gives the rejection rule for over-long lifetimes. It stops short of contrasting against other create_* siblings (e.g. create_authorization), so an agent has clear context but no explicit when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, so safety is partly covered. The description adds genuinely useful context beyond the annotations: credentials become visible in the AI conversation context (a security caveat an agent must surface), plus the authentication/session prerequisite. It does not explain storage durability or whether re-storing overwrites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks, purpose front-loaded ahead of the caveat and access requirements. The 'Note:' and ACCESS run-on are slightly chatty but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is needed for a store operation, and annotations carry the safety profile. With a nested credential object and a security/privacy caveat, the description covers what an agent needs to call it correctly; only sibling differentiation and overwrite/return behavior are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with provider and credentials both documented inline including examples and a nested arbitrary-key object. The description adds no additional meaning about accepted provider identifiers or expected credential keys, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Store DNS provider credentials for automated domain verification' tells the agent exactly what is persisted and why. It does not, however, distinguish itself from near-siblings such as connect_dns_provider, add_verification_provider, or verify_domain_with_credentials, so the agent cannot route on the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The access note gives a real precondition (Proof account + authenticate via /mcp or start_login) which is actionable usage guidance. But there is no guidance on when to choose this tool over the other credential/connection tools, and no explicit when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is partly covered. The description adds genuinely non-structured context: the required Proof account, the authenticate-then-retry loop, and the 'start_login does NOT open this tool' exclusion. It does not describe failure modes or the created object's persisted identity, so it stops short of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three clearly labeled blocks (purpose, Agent usage, ACCESS) with the core purpose front-loaded. The parenthetical Claude Code UI instruction is slightly operational noise, but the sequencing detail earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a fully documented 3-parameter schema, the description supplies everything else an agent needs: the prerequisite chain, the consuming tool, and the auth precondition. Nothing required to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that 'channels' determines approval request routing and that Telegram channel entries need a chat_id obtained via create_chat_id_discovery, tightening the meaning of the only non-obvious parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a HITL ... config') and immediately clarifies what the resource controls ('which messaging channels receive approval requests and the default timeout'). The 'Create' verb plus the resource name distinguishes it from update_hitl, delete_hitl, and list_hitls without needing schema inspection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly sequences this tool against named siblings: request_hitl_authorization must be called afterward, create_chat_id_discovery is required first for Telegram channels, and the config is consumed by create_confirmation. This is exactly when/when-not/alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real context beyond the annotations (readOnlyHint=false, destructiveHint=false): the tool creates a pending challenge that a human approves/denies out-of-band, that it requires an authenticated Proof account, and that it stays pending until one of six terminal states. Auth requirements and lifecycle are disclosed. It stops short of describing expiry timing, notification behavior, or idempotency, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, well-front-loaded blocks: purpose, agent usage, access. Each sentence carries information, though the ACCESS paragraph is slightly tangential to the tool's semantics and could be tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully compensates by telling the agent the returned ID is the polling handle and enumerating terminal states. Missing only failure/timeout expectations and the shape of the returned object, which keeps it at 4 for a stateful multi-step tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine meaning to suspicious_channel by explaining it drives which channel the approval must come from ('different from the one the suspicious contact reached the member on') — the security-relevant relationship the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ('Create a Proof-Me cross-channel identity challenge (CONFIRM) for an enrolled Circle member') and explains the mechanism — the holder approves on a different channel than the suspicious contact used. It is specific, but it does not explicitly contrast itself with lookalike siblings such as create_multi_channel_verification, create_confirmation, or create_hitl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: use for an enrolled Circle member whose suspicious contact needs cross-channel confirmation, then poll get_identity_challenge with the returned ID until it leaves pending. It names the follow-up tool and terminal states, but never states when NOT to use this versus other verification/confirmation creation tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false and destructiveHint=false, yet the description adds substantial behavior: losing sibling channels are cancelled, exactly one proof is billed at the winning channel and nothing at creation, and the tool requires an authenticated Proof account (start_login does not unlock it). These are non-obvious side effects and prerequisites an agent cannot get from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the first sentence nails the core mechanic, the billing constraint follows, then agent usage and the rendering caveat. Every sentence carries operational information, though the block is long enough that a reader must work through three paragraphs to reach the polling instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description fully documents the return shape (group_id, channels array with deep_link/sms_message/qr_text), the follow-up polling tool, the billing model, and the auth prerequisite. Nothing needed to invoke and correctly handle this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: it explains the first-wins semantics of the channels array and documents the response shape (group_id vg_<hex>, per-channel deep_link vs sms_message, and qr_text as pre-rendered art rather than an alternate address).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a multi-channel phone verification') and immediately defines the mechanism: one number challenged over several channels with OR / first-wins semantics. This distinguishes it from the single-channel create_verification / start_add_phone siblings without the agent needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete follow-up routing: pass deep_link to render_auth_link, poll get_multi_channel_verification_status with the group_id, and an explicit caveat about not relying on tool-result rendering. It never explicitly states when to prefer this over create_verification (single channel), so it stops just short of a full when/when-not treatment.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation with destructive potential. The description adds the authentication prerequisite, which is genuinely useful behavior context. But it does not explain what gets destroyed or made irrecoverable despite the destructiveHint, nor what the response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and followed by access guidance. The field enumeration is slightly redundant with the schema but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the action and auth prerequisite, and the schema fully documents all 10 optional parameters including nesting. However, for a destructive create with no output schema, the description omits what a created profile returns and what destructive effects the destructiveHint implies, leaving gaps an agent may need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with per-property descriptions, enums and patterns, so the schema carries the parameter burden. The description only groups field names (display name, bio, avatar, business info, email branding, theme) which roughly maps to parameters but adds no format, default, or interaction semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb (Create) and resource (new profile) and enumerates the configurable fields in one sentence. It does not explicitly differentiate itself from siblings like update_profile, update_my_profile, or set_primary_profile, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS note gives a clear prerequisite and recovery step (authenticate the client, then retry; start_login does not open this tool). However, it never contrasts create_profile with update_profile or set_primary_profile, leaving the choice between them only implied by the verb 'Create'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the mutation safety profile (readOnlyHint=false, destructiveHint=false), and the description goes well beyond that: it enumerates the three return artifacts, defines the terminal states (verified, failed, expired), and warns that clients fold tool results away so the agent must surface the link/text in its own reply. It also discloses the authentication prerequisite and that start_login does not cover this tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and return values are front-loaded, and the workflow guidance is actionable rather than filler. It runs to four paragraphs and the "user does not see tool results" note is a general client-behavior aside that is slightly tangential to this specific tool, but nearly every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining returns and does so concretely (deep_link, qr_code as base64 PNG, qr_text as terminal-display QR art). Combined with the auth requirement, the downstream wait/poll path, and terminal states, an agent has everything needed to create and follow through on a session.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter (channel, phone_number, metadata, template_id, callback_url, external_user_id) is documented in the schema itself. The description adds no parameter-level meaning such as format hints, defaults, or interactions, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create a new phone verification session") and adds scope context ("hosted verification flow with callbacks"), which helps separate it from plain create_verification. However, it never explicitly distinguishes itself from close siblings like create_verification, create_multi_channel_verification, or create_verification_request, leaving that inference to the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit ordered workflow: pass deep_link to render_auth_link, then use wait_for_session to poll to a terminal state. It also states a clear when-not rule ("Never hand qr_text to a link renderer") and names the alternative tools by name, so selection and sequencing require no inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false). The description adds non-obvious behavior beyond the annotations: the request targets another user, the session/auth flow required to make the call succeed, and the shape of each asset object. It still says nothing about request lifecycle (e.g., what happens on expiry or partial sharing), but the auth disclosure is substantive added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks: purpose first, then the access prerequisite. The single illustrative asset example is arguably redundant with the schema, but nothing is padded and the most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with nested objects and no output schema, the description covers purpose and auth but omits tool-selection context against numerous siblings and any note on the request's lifecycle or response. It is adequate to invoke the tool, but not complete enough to route confidently among the create_* family.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every one of the 10 parameters, including the nested asset object and action_context, is documented in the schema with defaults and constraints. The description's asset example ({"type": "email"}) only restates what the schema already provides, so it earns the baseline 3 with no compensating detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Create a new verification request") and clarifies the object ("ask another user to share verified assets"), which is more informative than the bare name. However, it never distinguishes this tool from close siblings such as create_verification_request, create_verification, or create_multi_channel_verification, leaving the agent to guess which request-creating tool applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS paragraph gives a real precondition (a Proof account) and an actionable recovery path (authenticate via /mcp or call start_login, then retry). That is genuine usage context, but there is no guidance on when to choose this tool over the many other create_* request tools, so selection among alternatives is left entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false/destructiveHint=false; the description goes well beyond that, disclosing the key-dependent branch where a telegram_bot call with a LIVE key returns status 'verified' with a proof token and no challenge while a pk_test_ key stays pending, that deep_link is returned on messenger channels, that no qr_text is returned, and the auth prerequisite for the Proof account. This is rich behavioral context an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded: purpose first, then agent usage, then the channel-specific behavior, then the critical note that users don't see tool results. It is long and carries some detail that could be trimmed (e.g. the parenthetical enumeration of asset types), but nearly every sentence conveys actionable behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object, no-output-schema creation tool, the description covers the required inputs, the channel-dependent response shape, the follow-up polling/link path, and the auth requirement, which is everything an agent needs to call it correctly. The absence of an output schema is compensated by the explicit description of the challenge/status/proof-token responses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, and the description adds concrete value by pairing parameter values in examples (type 'phone', channel 'sms', identifier '+37060000000'; type 'email', channel 'email'), clarifying how the three required fields combine. It does not explain the optional fields (bot_token, dns_provider, email_prefix, proof_expiry_days), but the schema already documents those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new identity verification') and enumerates the asset types it covers (phone, email, domain, social, wallet, account, Telegram bot), which is far more than a restatement of the name. It does not, however, differentiate itself from near-identical siblings like create_verification_request, create_multi_channel_verification, or trigger_verification, leaving an agent to guess which creation entrypoint applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete invocation guidance ('pass the asset type, the delivery channel, and the identifier') with worked examples, and explains the downstream flow (poll get_verification or use wait_for_verification for OTP; deep link for Telegram/WhatsApp). It stops short of stating when to prefer this tool over the sibling creation tools, so the guidance is clear but not exclusionary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, which frames the write-but-non-destructive nature. The description adds genuinely valuable behavioral context the annotations lack: the authentication/access requirement and the fact that start_login will not unlock this tool. It says nothing about side effects (what request records are created, whether requests are cancellable), so with annotations carrying part of the load a 3 is right.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight paragraphs, front-loaded with the core purpose and followed by a clearly labelled ACCESS block. No filler, though the purpose sentence and the asset-type list have some redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with nested objects and no output schema, the description covers the access model well and the schema covers inputs fully. It omits anything about the return value (request ID, status handle) and how the created request is later consumed — e.g., get_verification_request or wait_for_verification — which an agent needs to complete the workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter — assets, expires_in, partial_ok, action_type, callback_url, proof_expiry_days, etc. — is self-documented in the schema. The description adds no syntax, defaults, or format detail beyond what the schema already states, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a multi-asset verification request') and enumerates the asset types it handles, which distinguishes it from single-asset tools like create_verification. However, it never explicitly differentiates itself from the very similarly named sibling create_multi_channel_verification, leaving the agent to guess between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a real usage prerequisite — a Proof account is required and the client must authenticate first, plus a useful exclusion ('start_login does NOT open this tool'). But it gives no guidance on when to choose this over create_verification or create_multi_channel_verification, which is the key routing decision implied by the sibling set.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, but the description corrects the over-broad reading by disclosing this is a non-permanent archive with a documented restore path — exactly the kind of nuance annotations cannot express. It also states the authentication prerequisite and the required re-invocation after authenticating.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the operation and its soft-delete semantics in the first clause, with supporting detail after. The auth note is a separate paragraph and earns its space, though the phrasing is slightly repetitive ('Authenticate this client' / 'start_login does NOT open this tool').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation tool with no output schema, the description covers what changes, the observable effect (drops out of the default list), recoverability, and the auth gate. An agent has everything needed to invoke it correctly or recover from an auth failure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single id parameter is already documented as 'Circle ID to archive' with a hex pattern. The description adds no format, source (where to obtain the ID), or validation detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource (archive a Circle) and immediately qualifies it as a soft delete that sets status to archived. This distinguishes it from hard-delete siblings like delete_domain or delete_template, which an agent browsing the large sibling list would otherwise conflate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete consequences and a recovery path (recoverable via list_circles with status="archived"), and adds an important routing caveat that start_login does not unlock this tool. It does not compare against update_circle for non-destructive status changes, so the alternative comparison is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the downstream effect on domain verification and the authentication prerequisite, including the session flow via start_login and the /mcp authenticate step.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The destructive effect is front-loaded in the first two sentences, with the auth instructions clearly separated. The auth paragraph is a bit long but every line conveys actionable information about how to obtain access.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter destructive tool with no output schema, this covers the essential concerns: what is destroyed, the downstream impact, and how to authenticate. Nothing critical is missing, though explicit routing to sibling tools could improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter ('id') and schema description coverage is 100%, so the schema already documents it fully. The description adds no additional meaning about the id format or source, matching the baseline 3 for schema-documented params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete a stored DNS provider credential'), which is distinguishable from create_dns_credential, list_dns_credentials, and check_domain_credentials. It does not explicitly name those siblings, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the consequence of deletion (affected domains need new credentials for automated verification), which implies when the tool matters, but it never states when to use this versus alternatives or prerequisites for choosing a credential to delete. Usage is implied rather than directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond destructiveHint=true: discloses that it revokes all proofs and delegations irreversibly (re-adding doesn't restore them), deletes records, removes _proof TXT/Resend sending domain where possible, lists leftover manual cleanup in the response, and requires owner auth plus 2FA. This is exactly the context annotations can't carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: irreversible consequences first, then auth prerequisites, then the alternative. Long sentences but every clause carries needed warning. Slightly heavy but justified for a destructive op.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a destructive single-param tool: covers cascade effects, irreversibility, auth/2FA flow, leftover cleanup, and an alternate path. No output schema, so noting the response content (list of manual leftovers) fills that gap too.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single id is documented ('Domain ID to delete'); description reinforces that id is the domain id used as target but adds little beyond schema. Baseline 3-4 appropriate given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Remove a domain') and precisely enumerates the cascade consequences. Distinguishes clearly from revoke_asset and delete_domain_verification by naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the alternative 'revoke_asset' for the case of only needing a fresh proof, and states the exact precondition (owner, start_login session, start_2fa_for_action with action_type domain_remove and targets [id]). When-to-use/when-not are unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint annotation, the description discloses that nothing is revoked for unverified attempts, the exact error code (domain_verified) for the refused case, what revocation would entail, and the authentication requirement for a Proof account. It also warns that start_login does not open this tool, which is a non-obvious access constraint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and efficiently separated into an ACCESS note. The first sentence is long and slightly tangled (the delete_domain/start_login clause is hard to parse on first read), but overall it earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a destructive one-parameter tool with no output schema: it covers the eligible states, the refusal case and error code, the auth precondition, and the sibling alternative. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single fully-documented id parameter, so the schema already carries the parameter burden. The description adds nothing about the id format or origin beyond what the schema states — baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (delete a domain verification attempt) and narrows scope precisely to the non-verified states (pending, verifying, failed). It explicitly distinguishes itself from delete_domain, so an agent can tell the two apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the exclusion clearly — verified or needs-re-verification domains are refused with domain_verified — and routes the agent to the correct alternative (delete_domain in a start_login session or the dashboard). This is explicit when/when-not guidance with a named fallback.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, but the description adds real value beyond them: the operation is an archive rather than an irreversible purge, the resulting state is 'archived', and downstream confirmations stop working. It also discloses the auth precondition, which annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core operation and its consequence are front-loaded in two tight sentences. The trailing ACCESS block is boilerplate-heavy and the clause 'start_login does NOT open this tool' is awkwardly worded, slightly diluting the otherwise efficient structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation with no output schema and safety already covered by annotations, the description supplies the lifecycle consequence and auth requirement an agent needs. The oddly phrased auth note leaves minor ambiguity about the exact authentication flow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single required 'id' parameter, so the schema already documents it fully. The description adds no format, sourcing, or validation detail for the ID, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete (archive) a HITL config') and immediately clarifies that deletion is a soft-archive via status change, which separates it from hard-delete siblings like delete_hitl_keys. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a usage consequence ('Cannot be used for new confirmations after deletion') and an access precondition (needs a Proof account, authenticate first). It does not explicitly route to alternatives such as update_hitl or delete_hitl_keys, so it falls short of a full when/when-not statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantially more: the concrete consequence that existing ciphertexts become permanently unreadable, plus the auth requirement and the fact that start_login does not unlock this tool. This is exactly the extra context the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The destructive warning is front-loaded in the first sentence, which is the right ordering. The ACCESS paragraph is somewhat boilerplate and slightly verbose, but each part (warning, prerequisite, auth steps) carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive one-parameter tool with no output schema, the description covers the critical unknowns: irreversibility, auth prerequisites, and the workaround path. It falls short only in not relating the tool to its near-neighbor delete_hitl, which would help disambiguation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter (hitl_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or sourcing detail for the ID, which is acceptable given the high coverage but earns only the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Delete the encryption keypair from a HITL config.' This distinguishes it from siblings such as delete_hitl, get_hitl_keys, and upload_hitl_keys, so an agent can identify the exact target of the operation without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear prerequisite ('needs a Proof account', authenticate then retry) but never states when to choose this tool over alternatives like delete_hitl, nor when not to delete keys. Prerequisite guidance is present; alternative-selection guidance is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive=true and readOnly=false, and the description goes well beyond by disclosing exactly what is destroyed vs. preserved (history kept but unlinked, username retired for good), irreversibility ('Cannot be undone'), auth requirement ('needs a Proof account'), and the 2FA gate with concrete parameters. This is the level of behavioral detail an agent needs before invoking an irreversible mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and its effects, then layers the preconditions and auth flow in a logical order. Dense but every sentence carries operational weight. The ACCESS paragraph is slightly verbose but necessary given the auth complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, irreversible mutation with no output schema, the description covers what is destroyed, what is preserved, the last-project/primary constraint, the empty-project-only restriction under API-key auth, the 2FA requirement with exact call parameters, irretrievability, and the response hint ('the response names it'). Nothing an agent needs to call this safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds real value by tying profile_id to the 2FA action targets ('targets [this project id]'), clarifying the parameter's role in the auth flow. Only the bare schema field name 'Profile ID' is otherwise undocumented, but the description compensates adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (delete) and resource (project/profile), then enumerates precisely what deletion entails: revoking API keys, archiving HITL setups, declining pending requests, unlinking history, deleting templates, retiring the username. Distinguishes itself from update_profile/create_profile and other delete_* siblings through the profile scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly covers when it can and cannot be used: last project cannot be deleted, primary deletion reassigns primary to oldest remaining, and with an API key only an EMPTY project can be deleted (otherwise owner_session_required). Names the required start_2fa_for_action call with exact action_type and targets. This is a textbook when/when-not/precondition specification.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them: the exact effect of deletion (revert to channel/message-type default) and the authentication requirement, which an agent cannot infer from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its effect in one tight sentence; the ACCESS paragraph is separated and scannable. The auth note is slightly verbose but earns its place as an operational prerequisite.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, no-output-schema mutation tool, the description covers the effect, the auth prerequisite, and the parameter-driven default. It omits edge-case behavior (e.g. what happens if no custom template exists) and reversibility, which would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents channel, message_type, and profile_id (including the omitted-profile default behavior). The description only frames that the default is determined by channel and message type, adding marginal meaning over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('delete ... custom template') and adds the consequential effect (reverting the project to the default template for the channel and message type). This clearly distinguishes it from siblings like update_template, get_template, and list_templates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete prerequisite for use: a Proof account with an authenticated client, and explicitly notes that start_login does NOT open this tool (a useful exclusion that prevents a wrong path). It does not explicitly name an alternative tool for modifying vs. removing templates, so it falls short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses the 10,000-record cap, the supported filter dimensions, and a critical auth caveat (needs a Proof account; start_login does NOT open this tool). That last point actively prevents a wrong recovery path an agent would otherwise attempt.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, filters and limit in one compact sentence, then a clearly separated ACCESS block. The Claude Code parenthetical adds a little verbosity but carries actionable routing detail, so it largely earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-optional-parameter read-only export with full schema coverage and no output schema, the description covers what matters: formats, filters, record ceiling, and authentication. It does not mention pagination/truncation behavior when the 10,000 cap is hit, a minor remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both enums are documented in the schema, so the baseline of 3 applies. The description adds no per-parameter detail (e.g., date format nuances or default behavior) beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Export authorizations") plus output formats, so an agent knows exactly what it produces. It does not explicitly distinguish itself from siblings like export_data or list_authorizations, which is the only reason it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: use when you need CSV/JSON export with date-range and status filtering, and states the access prerequisite. It never names alternatives such as list_authorizations or export_data for when a plain listing or different dataset is wanted, so no explicit when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining that the export is prepared asynchronously in the background, that the data is delivered via an emailed link rather than returned by the tool, the 24-hour rate limit (waived for deletion-scheduled accounts), and the 7-day retention. These are exactly the operational traits an agent needs and that annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose then behavior, and nearly every sentence carries unique information. Slight redundancy: authentication is covered both in the main body ("sign in with start_login first") and again in the trailing ACCESS paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully compensates by explaining that the tool never returns the data itself and how delivery occurs. Auth requirements, rate limits, retention, and re-call semantics are all present, so an agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one optional parameter, and schema coverage is 100%, so the schema already documents export_id. The description's "Pass export_id to read one export's status" largely restates the schema text, adding only minor reinforcement; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Export a complete copy of your account's data") and explicitly covers the dual mode ("or check on one"). It cites the legal basis (GDPR Articles 15 and 20), which disambiguates it from the similarly-named export_authorizations sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use mechanics: first call starts the export, subsequent calls report readiness, and export_id reads a specific one. It also states prerequisites (owner only, sign in with start_login, API-key-only connections are refused) and the alternative path when not yet authenticated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already covered; the description usefully adds that authentication is required and how to obtain a session. It still omits behaviorally relevant details for a mutation: how much the expiration is extended, whether there are limits or one-shot restrictions, and what happens if the request is no longer pending.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in the first sentence, and the auth instructions follow as a clearly separated paragraph. It is slightly verbose for a one-parameter tool, but every sentence carries operational information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should ideally hint at the result of the extension, and it does not. The auth prerequisite is fully covered, but the agent still lacks detail on extension magnitude and edge cases for this mutation, leaving it minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the sole parameter 'id' is documented in the schema as 'Verification request ID to extend', so the description cannot add much. It contributes no format, source, or lookup guidance for obtaining the ID, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Extend the expiration time of a pending verification request'), which pinpoints the operation precisely. It doesn't name a sibling alternative, but the mutation semantics and the 'pending' qualifier make the target object unambiguous against the large sibling set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS paragraph gives concrete operational prerequisites (Proof account, authenticate via /mcp, or start_login) and even notes that start_login opens a session, which is genuine usage context. However, it never says when to extend versus when to cancel or recreate a request, e.g. how it relates to cancel_verification_request.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only assert readOnlyHint=true, but the description adds substantial behavior beyond that: the meaning of each terminal state, polling cadence, the auth prerequisite (needs a Proof account; authenticate via /mcp or start_login), and the non-obvious requirement that the user-facing reply text must already surface the challenge link/SMS before this call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and return states are front-loaded in the first sentence, and the polling/terminal-state guidance follows logically. Slightly long across three paragraphs with some overlap between the return-state list and the terminal-state explanation, but every section carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating the possible status values and their meanings. Auth requirements and the pre-call reply-text obligation are also covered, so an agent has everything needed to call and interpret this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single session_id parameter is fully documented in the schema, so the schema already carries the semantics. The description says 'by session ID' but adds no format, provenance, or sourcing detail beyond it, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check the status of a 2FA session by session ID') and enumerates the return states (completed/pending/expired), which lets an agent separate it from siblings like verify_2fa, wait_for_2fa, and start_2fa without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong operational context: poll after start_2fa, cadence of 'every few seconds', and explicit terminal-state handling ('verified' proceed, 'expired' restart with start_2fa). It does not, however, mention the sibling wait_for_2fa, which is the obvious alternative to hand-rolled polling, so the alternative-space is not fully closed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description is consistent with a read-only status check. It adds real operational context beyond the annotations: the tool requires an authenticated Proof account and describes the auth flow (authenticate via /mcp or start_login). It stops short of describing lifecycle/polling behavior of the in-progress session.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in one tight sentence, followed by a clearly separated access note. The access block is somewhat verbose but each clause carries actionable information for an agent hitting an auth failure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should ideally describe what status values are returned and whether polling is expected; it does neither. It also omits where session_id comes from. The auth guidance is helpful but leaves these functional gaps for a status-check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the single parameter is already documented as 'Add-email session ID'. The description restates 'by session ID' but adds no origin or format information beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Check the status') and resource ('in-progress email addition') with the keying field ('by session ID'). The email resource implicitly separates it from the sibling get_add_phone_status, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives access/authentication guidance (needs a Proof account; authenticate or use start_login). However, it does not say where the session_id originates (presumably start_add_email) or when to prefer this over wait_for_verification or get_add_phone_status, so the when-to-use guidance is incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true is consistent with a status-check tool, and the description adds behavior the annotation does not: this is a polling endpoint that should be called repeatedly until a terminal state, and it requires an authenticated Proof session (possibly created by start_login). It stops short of naming the terminal states or rejection behavior, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by polling and auth guidance. The paragraph about making sure the link/SMS appears in reply text is a little verbose and tangential to tool selection, but it does carry task-relevant guidance rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should say more about what a status response contains and which states count as terminal (e.g. complete, expired, failed). Authentication and polling behavior are covered, but the return-side picture is left entirely to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single session_id parameter is already documented in the schema as the add-phone session ID. The description repeats 'by session ID' without adding format, provenance, or lifecycle detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check the status of an in-progress phone addition') plus the input key ('by session ID'). It is readily distinguishable from start_add_phone and from the sibling get_add_email_status, so an agent can pick it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating guidance ('Poll until terminal state') and spells out the authentication path — authenticate the client, or sign in via start_login since that session opens this tool, then retry. It lacks an explicit 'do not use for X' exclusion, but the context is otherwise unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, it discloses that counts only are returned with no recipient identifiers, that counts aggregate the key plus every key it replaced (api_key.replaced_key_ids), and it spells out the authentication path (Proof account, /mcp auth or start_login). This is exactly the extra behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, front-loaded with what gets returned, followed by an access note. Nearly every sentence earns its place; the access paragraph is slightly verbose but justified for an auth-gated tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the burden of describing return contents (count categories plus attribution_cutoff_at and attributed_fraction) and the auth requirement. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real semantic meaning for id: the counts cover the key and every key it replaced, clarifying that id aggregates a key lineage. It does not add anything about the environment parameter beyond the schema's own default note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource (per-API-key usage for a given key id) and enumerates the exact metric families returned: verification counts by type/channel/status plus request/confirmation/authorization totals. It is clearly distinguishable from siblings like get_usage, get_self_api_key, and list_api_keys, which cover different scopes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the operative constraint clearly: 'an API-key caller may read only its own key' and that usage is scoped to the authenticated account, which tells the agent when this tool is applicable. However, it never explicitly contrasts this with get_usage or get_self_api_key, leaving the agent to infer the choice among overlapping usage tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=true; the description adds the account requirement ('needs a Proof account'), the exact authenticate flow, and the anti-pattern around start_login. That is meaningful behavioral context beyond the annotation, though return format/pagination behavior remains unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks: what it returns first, then the access prerequisite. Front-loaded and mostly waste-free, though the parenthetical UI path is slightly verbose for an agent audience.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description usefully enumerates the returned fields, and it covers the auth prerequisite that would otherwise cause a failed call. Adequate for a single-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'id' parameter, so the schema already carries the semantics. The description adds nothing about ID format or validity, making 3 the correct baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get a single verified asset by ID') and enumerates the returned fields (type, value, status, timestamps). The word 'single' implicitly distinguishes it from list_assets, but no sibling is named explicitly, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear authentication precondition and, unusually, an explicit negative routing hint: 'start_login does NOT open this tool,' steering the agent away from a wrong recovery path. It does not, however, say when to prefer this over list_assets or get_profile_assets.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already carry readOnlyHint=true, but the description adds value beyond that: it discloses the authentication requirement and the 401-style retry flow, and warns that start_login does NOT unlock this tool — a genuinely non-obvious behavioral caveat. It stops short of describing response shape in depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the return contents, then the access caveat. Two sentences plus a short ACCESS block; the anti-pattern warning about start_login earns its place, though the ACCESS paragraph is slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming the returned fields (status, usage statistics) and covering the auth prerequisite. Nothing critical to invoking a single-param read is missing; only edge cases (not-found/error behavior) are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter with 100% schema description coverage, so the schema already documents `id` as the Authorization ID. The description's 'by ID' adds no syntax or format detail beyond that, which is the correct baseline-3 outcome.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get an authorization by ID') and adds what the response contains (status and usage statistics). It implicitly separates itself from list_authorizations and create_authorization/revoke_authorization by emphasizing single-ID lookup, though it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete prerequisite (Proof account, authenticate the client, then retry) which is real usage guidance, but gives no when-to-use/when-not against alternatives like list_authorizations or get_verification_request. Usage is implied rather than framed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond readOnlyHint=true: it discloses the authentication prerequisite, the shape of the returned payload, and a security constraint that an identifier is never returned (SEC-PM-006). That is meaningful behavioral disclosure for a read tool, though it omits error/not-found behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, return contents, and access protocol are front-loaded and ordered logically. The opaque SEC-PM-006 reference is the only bit of noise, but it does not bloat the description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly takes on the burden of describing what is returned, and it covers the auth prerequisite that an agent would otherwise trip over. Missing only failure/error semantics for a nonexistent ID.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'id' parameter is fully documented there (including the 24-hex pattern). The description restates 'by ID' but adds no format, constraint, or example beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a Circle by ID') and even enumerates the returned payload (members, channel presence booleans). It implicitly separates itself from list_circles via 'by ID', but does not name any sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a real usage gate – requires a Proof account, must authenticate the client first, and start_login does not cover it – which is helpful. However it says nothing about when to prefer this over list_circles, list_circle_members, or get_circle siblings, so selection guidance is only implied by the 'by ID' framing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint already declaring the safe-read profile, the description adds genuine non-obvious behavior: the auth requirement and the counterintuitive warning that start_login does not unlock this tool. It also previews the returned fields. It stops short of covering error cases or whether an unknown ID returns empty vs. raises.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks, both front-loaded: purpose and return value first, then the access prerequisite. No filler sentences, though the auth note could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming the return payload. Combined with the readOnly annotation and the auth prerequisite, an agent has everything needed to call this correctly: what it does, what comes back, and what access it requires.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents it. The description adds only the implicit notion that the ID refers to an existing confirmation and nothing about format or sourcing. Baseline 3 when the schema carries the parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a confirmation by ID') and even enumerates the return payload (status, response, proof token). This distinguishes it from list_confirmations and create_confirmation by the ID-based lookup, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a real prerequisite ('needs a Proof account', authenticate the client, and start_login does NOT open this tool), which is useful gating context. However, it offers no routing guidance among the many related siblings such as list_confirmations, wait_for_confirmation, or get_confirmation_approval_link, so when-to-use versus alternatives remains implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false / destructiveHint=false. The description adds real behavioral context: the link expiry inherits the confirmation timeout, the pending-state precondition, and that a Proof account with an authenticated client is required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences up front, followed by a clearly separated ACCESS note. Every line carries information, though the auth block is slightly verbose for a one-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description covers precondition, expiry semantics and authentication, which is most of what an agent needs. It omits what the returned link looks like and whether regenerating invalidates prior links.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single 'id' (24-hex Confirmation ID) already documented. The description refers to confirmations but adds no format or scoping detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Generate') and resource ('approval link for a pending confirmation'), and the qualifier 'fresh' distinguishes it from merely fetching a confirmation via get_confirmation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear precondition ('Only works for pending confirmations') and an explicit auth procedure, including the negative hint that start_login does NOT unlock this tool. It stops short of naming a sibling alternative for pulling an existing link.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With only readOnlyHint available from annotations, the description carries the auth burden and does it well: it discloses that a login session is required, that an API key is insufficient, and that a Proof account/authentication step is needed. It stops short of describing rate limits or response shape, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then prerequisites, then alternatives. The ACCESS paragraph largely repeats the login instructions already given in the first paragraph, which is the only real redundancy, but the content still earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description gives only a coarse sense of the return ('account details, plan and settings'). Given the zero-parameter, read-only nature and the thorough auth guidance, this is close to complete, with the return shape being the remaining soft spot.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description correctly avoids inventing parameter semantics and instead spends its words on auth context, which is the only caller-relevant input here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get the signed-in user's account details, plan and settings') and explicitly distinguishes itself from lookalike siblings (get_self_api_key, get_settings) by scoping to the signed-in user rather than the API key's own account.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the prerequisite flow (start_login, then wait_for_login until success), states the negative condition (an API key alone cannot read this), and routes to the correct alternatives for the API-key case. Nothing about selection is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already establishes this as a safe read. The description adds real behavioral context beyond annotations: the account requirement and the concrete authentication step ('/mcp → Authenticate, then call this tool again'), plus the warning that start_login won't unblock it. It stops short of describing return shape or pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in the first sentence, then adds a clearly separated access note. Both sentences earn their place, though the access paragraph is slightly verbose for a zero-parameter read tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, read-only list tool with no output schema, the description covers purpose and the authentication prerequisite well. Return format is not described, but with no output schema the burden is light and the definition is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify on the input side, and schema coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get all default message templates') and clarifies what 'default' means: built-in templates sent when no custom template exists. This implicitly distinguishes it from custom-template siblings like get_template/list_templates, but does not name an alternative explicitly, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful access context ('needs a Proof account') and a routing note that start_login does NOT open this tool, but gives no explicit when-to-use-vs-alternatives guidance relative to list_templates or get_template. Usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint; the description goes well beyond by disclosing the return payload (stored publishable token plus DERIVED effective_status/is_valid) and the derivation rule — validity is bounded by the underlying control proof (revoked/suspended/expired domain proof invalidates it) and by its own expires_at, whichever comes first. That is real behavioral context an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool does and what it returns, then a clearly separated ACCESS block. Information-dense but every sentence carries weight; the validity explanation is slightly verbose but justified given no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description supplies the return shape and the semantics of the derived status fields, and it supplies auth prerequisites. An agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single id parameter is fully documented, so the schema does the heavy lifting. The description restates both accepted formats (Mongo id, ph_dlg_* handle) but adds no syntax detail beyond the schema pattern, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Get) and resource (one delegation) plus the accepted identifier formats (Mongo id or ph_dlg_* handle). The singular 'one of your delegations' separates it from list_delegations and verify_delegations without needing their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit access prerequisites: needs a Proof account, how to authenticate (Claude Code /mcp → Authenticate), and an explicit warning that start_login does not unlock this tool. It does not state when to prefer this over list_delegations or verify_delegation, so it falls short of the 5 bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already declares the safety profile, so the description's added value is the authentication prerequisite: a Proof account is needed, and the first call may open a session that requires start_login followed by a retry. That is meaningful behavioral context an agent cannot get from annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short blocks: the capability statement first, then the access prerequisite. Both earn their place, though the auth note is slightly verbose and could be tighter without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no input parameters, no output schema, and readOnlyHint already covering safety, the description supplies everything remaining: what is returned (provider metadata, credential fields, doc links) and the auth flow required to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify further. No parameter-level claims are made or needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Get) and resource (metadata for all supported DNS providers) and enumerates the payload (required credential fields, documentation links). This clearly separates it from siblings like connect_dns_provider, create_dns_credential, and list_dns_credentials, which act on credentials rather than provider metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS paragraph gives real procedural guidance (Proof account required, authenticate via /mcp or start_login, then retry), but it never states when to choose this tool over alternatives such as list_dns_credentials or connect_dns_provider. Usage is only implied via the 'required credential fields' payload.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description goes beyond that by disclosing the authentication requirement and the recovery path (session opens this tool, then call again). It stops short of covering rate limits or response shape detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose sentence first, then a separate, clearly labeled ACCESS block. Both parts earn their place, though the auth block is slightly chatty with the parenthetical CLI hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-ID getter with no output schema, the description tells the agent what data comes back and how to satisfy the auth gate. Remaining gaps (pagination/error behavior) are minor for a lookup of this shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

One required parameter with 100% schema description coverage, so the schema already defines 'id' as the Domain ID. The description's 'by ID' only restates this, adding no format or sourcing detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get details of a specific domain by ID') and enumerates the returned content (verification status, DNS records, provider connections). It does not explicitly contrast itself with near siblings like check_domain_verification or check_domain_credentials, so it falls short of the top band.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear access prerequisites (Proof account, authenticate or start_login) but no guidance on when to prefer this over list_domains or the various check_domain_* tools. Usage is only implied by 'by ID'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds real context beyond readOnlyHint=true: it discloses the return payload shape (channels, timeout, status) and, importantly, the authentication precondition that the client must be authenticated for this specific tool. That prerequisite detail is not captured by annotations and is operationally significant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in one sentence, followed by a clearly separated ACCESS note. The parenthetical Claude Code hint is slightly verbose but serves a practical recovery path, and no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description covers purpose, return contents, and the authentication prerequisite. An agent has what it needs to invoke it correctly, with only the sibling-routing detail left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter clearly described as the 'HITL config ID' in the schema. The description's 'by ID' adds nothing beyond what the schema already states, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a HITL config by ID') and even names the returned fields (channels, timeout, status). It distinguishes itself from create_hitl/update_hitl/delete_hitl via the 'by ID' read framing, though it doesn't explicitly contrast with list_hitls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ACCESS block gives strong prerequisite guidance (needs a Proof account, authenticate first, start_login won't unlock this tool), which is genuinely useful. However, it offers no guidance on when to prefer this over list_hitls for retrieval, so usage is only implied by the 'by ID' phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint annotation by disclosing that the returned fields depend on the caller's permission scope — full material with hitl:read, only public_key/kid otherwise — and that private-key material is never exposed to confirmation-only keys. It also documents the Proof-account auth requirement, which annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return behavior, with access requirements in a clearly separated block. The access paragraph has minor redundancy ('Authenticate this client... then call this tool again'), but every sentence carries necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so thoroughly, enumerating the fields returned under each permission tier and stating the auth prerequisite. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and there is a single required hitl_id param, so the schema already documents it. The description refers to 'a HITL config' but adds no format, sourcing, or lookup guidance for the ID beyond what the schema provides, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get the encryption keypair for a HITL config'), clearly distinct from siblings like get_hitl, list_hitls, upload_hitl_keys, and delete_hitl_keys. An agent can identify the resource and operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong context: it explains the permission-conditional behavior (hitl:read vs confirmations:create) and states an explicit exclusion ('start_login does NOT open this tool') plus the auth prerequisite. It does not name sibling alternatives such as get_hitl or upload_hitl_keys, so routing guidance is good but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=true already covering the safety profile, the description adds real value beyond annotations: the full status enumeration, the channel returned, the proof token/proof_id arriving only after the subject decides, the account/auth requirement, and the polling-for-resolution behavior. It stops short of detailing pagination or error cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and return shape, then a clearly separated ACCESS block. Every sentence carries information; only minor verbosity in listing all nine status values keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description justifiably carries the return-value burden and does so by enumerating statuses and the proof payload. Combined with the auth prerequisite and polling guidance, an agent has everything needed to call and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter and schema description coverage is 100%; the schema already documents 'id' as the Identity challenge ID with a hex pattern. The description adds nothing beyond 'by ID,' so the baseline 3 for schema-driven parameter documentation applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Get a Proof-Me identity challenge by ID,' which cleanly separates it from create_identity_challenge and the sibling get_* tools. However, it never explicitly names or routes against an alternative tool (e.g. get_verification, get_multi_channel_verification_status), so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Poll this for resolution' gives a clear operational directive for when to call it, and the ACCESS block lays out the prerequisite (authenticated Proof account) plus the note that 'start_login does NOT open this tool.' No explicit when-not or named alternative is provided, so it is clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.