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

Annotations only cover readOnlyHint=false and destructiveHint=false; the description adds real behavioural context beyond that: the member is created in a 'pending' state, the Telegram chat id is bound later when the deep link is tapped, and the tool is gated behind an authenticated Proof account. It does not disclose error behaviour, idempotency, or what the call returns, so not a full 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, front-loaded paragraphs each doing distinct work: what the tool does, how it sequences with the sibling, and the auth prerequisite. No filler sentences.

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 annotations, full schema coverage, and no output schema, the description supplies the state (pending), the follow-up call, and the auth gate. It stops short of describing what is returned or what happens on failure, which is the only 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%, so id, name, and whatsapp_phone are already fully documented including the E.164 pattern and optionality. The description only restates 'by name' and 'optional pre-declared WhatsApp phone', adding no syntax or format meaning beyond the schema — baseline 3.

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 ('Add a pending member to a Circle') and immediately distinguishes itself from the neighbouring invite_circle_member by clarifying that this tool only registers the member while the enrollment link is minted elsewhere. An agent can select 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 an explicit sequencing rule ('after adding a member, call invite_circle_member') plus a hard precondition ('needs a Proof account, set PROOF_API_KEY and restart') and an explicit exclusion ('start_login does NOT open this tool'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 mark it as a non-read-only, non-destructive mutation. The description goes further by disclosing the 409 duplicate-channel-type response, server-side per-channel identifier validation, and the API-key prerequisite — concrete behavior 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?

Front-loaded with the action and error semantics, then the identifier formats, then access requirements. Two tight paragraphs with no filler sentences, though the ACCESS boilerplate is somewhat bulky relative to the payload.

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 the failure mode (409), identifier formats, and auth setup, which is most of what an agent needs. It stops short of describing the success response or whether re-adding after removal behaves differently.

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 four parameters are already documented. The description repeats the identifier format and adds that validation is server-side per channel, but contributes no new semantics for id, member_id, or channel. 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 (declare/add a channel for a Circle member) and names the artifact it operates on. It is recognizable against the sibling channel tools (list_circle_member_channels, remove_circle_member_channel) even though it never names them explicitly for contrast.

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 a real prerequisite and one negative routing hint ('start_login does NOT open this tool'), but there is no guidance on when to choose this tool over add_circle_member, invite_circle_member, or the channel-list tools, nor what preconditions the member must satisfy.

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. The description adds genuinely useful behavioral context beyond that: the operation requires an authenticated Proof account, must have PROOF_API_KEY set (with a server restart), and can be reached via a start_login session. It does not describe side effects or rate limits, so it is 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 a single sentence, followed by a clearly separated ACCESS paragraph. The auth note is somewhat long but earns its place by preventing failed calls; no filler sentences.

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 purpose, parameters, and the auth prerequisite, which is solid for a mutation tool. With no output schema, the description leaves unclear what a successful call returns or whether ownership is verified immediately, a meaningful gap for an add/verify 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 description coverage is 100%, so the schema already documents domain, for_email_sending, and verification_method. The description echoes the two optional params ('email sending intent and verification method') but adds no syntax or format detail beyond the schema, 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+resource ('Add a new domain') and adds the goal ('to verify ownership'), which lets an agent understand the intent. However, it does not distinguish itself from the many sibling domain tools (verify_domain, start_domain_verification, delete_domain), 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 description gives a prerequisite/route ('needs a Proof account' and use start_login if unauthenticated), which is useful invocation context. It does not, however, explain when to choose add_domain over the other domain-verification siblings, so usage guidance remains implied rather than 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?

Annotations declare destructiveHint=true and readOnlyHint=false. The description adds a critical behavioral warning the annotations don't: credentials will be visible in AI conversation context, which is a real security disclosure useful to the agent. It also explains the auth flow. Missing detail on what the mutation does to existing providers, but strong overall.

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 scope, followed by the security note and access info. Slightly more verbose on auth mechanics than necessary but every sentence carries weight.

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, it covers access, precondition, and the credential-visibility caveat. Doesn't describe return values or effect on existing providers, but adequately complete for the agent 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?

Schema description coverage is 100%, so the schema documents id, provider, and credentials. The description adds no syntax or format detail beyond what the schema provides. Baseline 3 is correct.

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 (Add), resource (DNS provider for verification), and scope (to an already-verified domain). This distinguishes it from siblings like connect_dns_provider and verify_domain_with_credentials.

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?

Specifies the precondition (an already-verified domain) and access requirements, which tells the agent when this applies. However, it doesn't explicitly name which sibling to use instead when the domain isn't yet verified.

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 known. The description adds real behavioral context beyond that: a creator-only authorization constraint and the exact auth flow (PROOF_API_KEY or start_login session) needed before the call succeeds. It stops short of describing post-cancel state (e.g., whether proofs are revoked).

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, with the permission constraint immediately after. The ACCESS block is multi-line boilerplate but is genuinely actionable remediation for an auth failure 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?

For a single-parameter destructive tool with no output schema, the definition covers purpose, permission scope, and authentication setup adequately. The main missing piece is disambiguation from cancel_verification_request and the resulting state after cancellation.

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% with an explicit description ("Verification request ID to cancel"). The description adds no format or sourcing 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?

Clear verb+resource ("Cancel a pending verification request") and it states the operation is limited to pending requests. However, it never distinguishes itself from the very similar sibling cancel_verification_request, and it uses "verification request" phrasing for a tool named cancel_user_request, which risks confusion with that sibling's family.

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 an important precondition ("Only the creator can cancel") and explains the account/auth prerequisite for calling it. It does not say when to prefer this over cancel_verification_request or other request tools, so usage is implied rather than fully guided.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real operational context beyond that: the state precondition (pending only) and the account/auth prerequisite (Proof account plus PROOF_API_KEY with a server restart). It does not describe what happens to state after cancellation, but the key blockers to a successful call are disclosed.

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 leading with the action and precondition, followed by a clearly separated ACCESS block. Nothing is redundant, though the access block's phrasing is slightly informal for a tool definition.

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 destructiveness already declared in annotations and no output schema, the description covers the essential prerequisites and state constraint. An agent knows what it needs before calling and what condition the target must satisfy.

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 with 100% schema description coverage ('Verification request ID'), so the schema already carries the meaning. The description adds no format, ID source, or lookup guidance, making this a baseline case rather than a value-add.

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 ('Cancel a pending verification request') with an immediate scope qualifier. It is clearly distinguishable from most siblings, though it never contrasts itself with the near-neighbour cancel_user_request.

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 applicability rule ('Only pending requests can be cancelled') and a useful negative routing hint ('start_login does NOT open this tool'), which prevents a common dead end. It stops short of naming cancel_user_request or list_verification_requests as the ways to find cancellable IDs.

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, so the description carries most of the load and adds genuinely useful context: it is a non-mutating credential probe and it requires a Proof account, with two concrete paths to authenticate (PROOF_API_KEY or start_login). It does not describe what a failed check looks like or any rate limits.

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 in the first sentence, followed by usage and then access notes. All three sentences carry distinct information; the ACCESS block could be tightened but is 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?

For a one-parameter, no-output-schema read tool, the description covers purpose, sequencing, and the authentication prerequisite. The main gap is that it does not say what the check returns or how to interpret a negative result, but that is a minor omission for a read-only probe.

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 ('Domain ID to check credentials for'), so the schema already does the work. The description adds no format or syntax 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?

Specific verb+resource: checking whether stored DNS credentials have access to a domain. It distinguishes itself from the verification siblings by framing itself as a pre-flight credential test, though it does not explicitly name the sibling it differs from (e.g. verify_domain_with_credentials).

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 states when to use it: 'Use before triggering verification to confirm the credentials work.' That gives a clear precondition and ordering relative to the verification flow. It does not spell out when NOT to use it, so it stops short of 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?

The description is consistent with readOnlyHint=true and adds useful context beyond the annotation: it requires a Proof account and either PROOF_API_KEY or a session opened via start_login. However, with no output schema it does not describe what the returned status looks like (e.g., verification states or DNS record fields), leaving the read's result shape undisclosed.

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: the first front-loads the purpose, the second handles the access prerequisite. No wasted text, though the ACCESS clause is somewhat verbose for what it conveys.

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 tool whose safety profile is already covered by annotations, the description supplies purpose and the non-obvious auth prerequisite. Only the return-value shape is omitted, which is a minor gap given the tool is a status read.

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 parameter ('id' documented as 'Domain ID'), so the schema already carries parameter meaning. The description adds no extra syntax, format, or ID-sourcing 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 (check) and resource (email sending setup status for a domain), plus the scope of what it inspects (DNS record configuration progress). It is clear on its own, but it does not explicitly differentiate itself from close siblings like check_domain_verification, setup_domain_email, or get_add_email_status, which an agent must disambiguate by name 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 description never says when to call this versus setup_domain_email, start_domain_email_verification, confirm_domain_email_code, or check_domain_verification, nor what prerequisite state should precede it. Only the auth prerequisite (PROOF_API_KEY or start_login) is stated, which is access guidance rather than 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?

Annotations only mark readOnlyHint=false and destructiveHint=false. The description earns credit by disclosing that this is not a passive read – it 'triggers a DNS/HTTP check' – and by stating the account/API-key prerequisite plus the non-obvious note that start_login does NOT grant access. Return content is only gestured at.

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, then side effect, then access requirement – front-loaded and tight, with no filler sentences. Both sentences earn their 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 one-param check tool with no output schema, the definition covers purpose, side effect, and the auth blocker. It could say more about what status values come back or whether repeated calls are rate-limited, but nothing critical for correct invocation 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?

Single parameter with 100% schema coverage ('Domain verification ID'), so the schema already carries full meaning. The description adds nothing about the id beyond the schema, which is the baseline-3 case for one param.

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?

Specific verb+resource: 'Check the status of a pending domain verification.' The scope qualifier 'pending' and the named side effect distinguish it from start_domain_verification and wait_for_verification, though neither sibling is 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?

Usage is implied ('pending' verification, i.e. after starting one) but there is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives like wait_for_verification or get_domain. The ACCESS block is auth setup, not usage 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 annotations only declaring that this is not read-only and not destructive, the description adds real operational context: it requires a Proof account, an API key env var, or an interactive login via start_login before it will work. That auth prerequisite is the kind of thing annotations cannot express. It does not describe idempotency or rate limits, so it is 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?

Two short sentences, action and trigger front-loaded, followed by the access note. No filler, though the access block is slightly dense and could be trimmed.

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, no-output-schema tool, the description covers the action, the trigger condition, and the authentication path needed to invoke it. It omits what the check's result signifies (verified vs. pending), which would be the one remaining nicety.

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 with 100% schema description coverage ('session_id' documented as the domain verification session ID), so the schema already does the work. The description adds nothing about the parameter's origin or format beyond 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 ('Trigger a check on the domain verification challenge') and clarifies the trigger point (after placing a DNS record or HTTP file). It reads clearly against most siblings, though it does not explicitly distinguish itself from the near-identically named check_domain_verification or get_user_domain_verification_status.

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 precondition: 'Call after placing DNS record or HTTP file.' That is a clear when-to-use signal. It stops short of naming an alternative (e.g., wait_for_verification or get_user_domain_verification_status) or stating when not to call it.

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 partly covered. The description adds meaningful context: the username must be unique, its format constraints, and the auth requirement. It stops short of saying whether the username can later be changed or what failure looks like on collision.

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 action, then constraints, then access requirements. No filler, though the constraint sentence slightly duplicates the 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?

For a single-parameter mutation with no output schema and minimal annotations, the description covers what it does, its constraint, and the auth precondition. It omits post-success behavior (return value, mutability of the username), a minor 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 single parameter is already fully documented with pattern and length bounds. The description restates the same 3-30 / alphanumeric-underscore rule, adding no meaning 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 (claim) and resource (username) with scope (authenticated user's public profile), plus uniqueness. Clear enough that an agent distinguishes it from profile/email/phone mutation siblings at a glance.

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 precondition context: a Proof account is required and the agent should either set PROOF_API_KEY or sign in via start_login before calling. It doesn't name exclusions, but there is no direct alternative tool, so routing guidance is largely moot.

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 a non-read-only but non-destructive operation, and the description goes beyond that by disclosing the access requirements: a Proof account, PROOF_API_KEY, or an authenticated session via start_login. It does not say what a failed or already-consumed code returns, but for a write tool with annotation coverage this is solid added 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?

Purpose is front-loaded in the first sentence and the auth/session note is clearly separated as an ACCESS block. The operational aside about restarting the server is slightly chatty but genuinely useful 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?

For a two-parameter write tool with a fully documented schema and no output schema, the definition covers purpose, prerequisites, and authentication path. It omits error/failure behaviour and sibling routing, which are the only meaningful 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% (id = Domain ID, code = Verification code with a 1-10 length constraint), so the schema already carries parameter meaning. The description only reinforces that the code comes from the corporate email; it adds no format or coupling detail beyond that, 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 (Confirm) and resource (domain email verification) plus the mechanism (submitting the emailed code), which separates it from start_domain_email_verification, check_domain_email_status, and resend_domain_email in the sibling list. It does not name any sibling explicitly, so an agent must infer the ordering from the verb rather than being told.

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 implies the prerequisite (a code must already have been sent to the corporate email) and gives setup guidance for auth, but it never states when to call this versus the neighbouring domain-email tools or what to do if the code has expired. Usage is inferable but not spelled out.

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 mutation profile is known. The description adds genuinely useful context beyond that: the API token will be exposed in the AI conversation, and authentication prerequisites are spelled out. It does not describe reversibility or what 'connecting' changes on the domain, keeping it 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 the action and purpose, followed by a security warning and the access requirement. Every sentence carries weight, though the ACCESS paragraph is somewhat long for what it conveys.

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 2-param tool with full schema coverage and annotations, the description covers purpose, the security implication of passing a token, and the auth prerequisite. No output schema exists, so no return-value explanation is required; the main omission is what changes on the domain after connecting.

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 as Domain ID, api_token as a DNS-edit token) are already documented in the schema. The description adds no syntax or format detail beyond that, 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 (connect), resource (Cloudflare API token), and target (a domain) plus the outcome (automated DNS record management). The provider name inherently distinguishes it from siblings like connect_godaddy and connect_dns_provider, though it never explicitly contrasts 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?

The ACCESS block explains prerequisites (Proof account, PROOF_API_KEY, or start_login) which implies when the tool is callable, but it never states when to choose this tool over connect_dns_provider or connect_godaddy. Usage context is present but alternatives are not addressed.

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 genuinely new context: credentials will be exposed in conversation context, plus the auth/session prerequisite. It stops short of saying what gets persisted or how to reverse the connection, but the security warning is real value beyond the 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?

Purpose is front-loaded in one sentence, the credential-exposure warning follows immediately, and the access block is clearly separated. Slightly more prose than strictly necessary 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?

For a destructive, credential-bearing mutation with no output schema, the description covers the operation, the security caveat, and the auth prerequisite. It could say more about what state is created or whether the connection is reversible, but an agent has enough 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 id, provider, and credentials are already documented. The description only restates that credentials are provider-specific key-value pairs, adding no format, naming, or validation 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 ('Connect a ... DNS provider to a domain') and the word 'generic' distinguishes it from the provider-specific siblings connect_cloudflare and connect_godaddy. An agent can identify the operation and its scope 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?

The ACCESS block gives concrete prerequisite handling (set PROOF_API_KEY, or use start_login then retry), which is useful. However it never says when to choose this tool over the specific-provider siblings like connect_cloudflare/connect_godaddy, so alternative selection is only implied by the word 'generic'.

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 destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds non-obvious value beyond that: it warns that the API key and secret will be visible in the AI conversation context, a real security disclosure, and states the account/session prerequisite. It does not say whether existing credentials are replaced, but the extra context is substantive.

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 the credential-visibility note, then access steps. Efficient and free of padding, though the ACCESS block reads slightly like procedural boilerplate 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?

For a destructive credential-connecting tool with no output schema, the definition covers purpose, security implications, and access prerequisites. It leaves some questions unanswered (what happens to prior credentials, whether the connection is validated), but the essentials needed to invoke it are 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% with all three parameters (id, api_key, api_secret) documented and required. The description adds no format or syntax detail beyond the schema, so the baseline 3 for high coverage 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 (Connect), resource (GoDaddy API credentials), target (a domain), and the benefit (automated DNS record management) in one sentence. An agent can distinguish this from connect_cloudflare and connect_dns_provider purely from the provider name in the description.

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; set PROOF_API_KEY or use start_login then re-call), which is useful context for invocation. However, it never explains when to choose this tool over sibling DNS-credential tools like connect_cloudflare, connect_dns_provider, or create_dns_credential, so selection guidance 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=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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that the secret is returned ONLY once, that it will be visible in the AI conversation context, that the operation requires an elevated 2FA session, and how to recover from a 403. This is exactly the behavioral context an agent needs for a credential-minting write operation.

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 highest-risk fact (secret returned only in this response, visible in context) before the procedural 2FA steps and the access note. Every section is distinct and earns its place given the operation's 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 credential-creation tool with no output schema, the description supplies the critical return-value warning, the full prerequisite flow, and the authentication context. Nothing an agent needs 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 coverage is 100%, so name/scopes/environment are already documented, establishing a baseline of 3. The description adds real semantic value for profile_id by explaining the branding effect ('outbound messages sent with the key are then branded as that project'), which the schema's 'sub-account project' phrasing only hints at.

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?

Opens with a specific verb+resource ('Create a new API key') and the description clearly differentiates this from siblings like list_api_keys, revoke_api_key, and regenerate_api_key. An agent can identify exactly what this 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?

Provides an explicit, numbered prerequisite flow (start_2fa with action_type 'api_key_create' → wait for user → poll get_2fa_status → call this tool) plus a documented failure path (403 means session expired, restart). It also names the authentication alternatives (PROOF_API_KEY vs start_login), leaving nothing 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 cover the safety profile (readOnlyHint=false, destructiveHint=false). The description adds genuine behavioral context beyond that: a human-approval gate before confirmations work, plus an account/API-key prerequisite. It does not describe rate limits or the returned artifact, keeping it 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?

Two tight paragraphs, purpose front-loaded, with the access prerequisite separated out. Every sentence carries weight; nothing is redundant, though the framing 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?

For a 9-param, 5-required create tool with no output schema, the description covers purpose, the human-approval workflow, and the account prerequisite. It omits what the creator receives back (e.g., an authorization identifier) and how to proceed afterward, which is the only notable 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 all 9 parameters (including channel/scope enums and the bsuid alternative to phone) are documented in the schema itself. The description adds no field-level syntax or format detail, 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 ('Create a new authorization request') and explains the resource's role: granting permission to send confirmations via a channel. This meaningfully distinguishes it from siblings like create_confirmation and request_hitl_authorization, 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?

Gives the ordering constraint (user must approve before confirmations can be sent) and a clear ACCESS prerequisite (Proof account, PROOF_API_KEY, restart). The exclusion 'start_login does NOT open this tool' usefully prevents a wrong path, but no explicit alternative tool is named for edge cases.

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/destructiveHint=false, the description carries real extra weight: it enumerates the return payload, states an account/API-key prerequisite and that start_login does not open this tool, and warns that users never see folded tool results. That is substantial behavioral disclosure beyond the annotations, and nothing contradicts them.

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 shape, then workflow instructions, then a prerequisite note. It is on the long side (~200 words) and the closing paragraph about clients folding tool results is somewhat tangential, but nearly every sentence carries actionable direction.

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 multi-step create-to-verify flow with no output schema, the description covers the return fields, the next tool to call, the polling loop, the terminal-vs-link distinction, and the account prerequisite. An agent has everything needed to drive the full HITL setup 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?

The tool takes zero parameters, so there is no parameter syntax to document and the baseline is 4. The description correctly focuses on the token it produces and the downstream calls instead of inventing 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?

Opens with a specific verb+resource: 'Create a Telegram chat ID discovery token,' then names the exact return fields. It is clearly distinguishable from siblings poll_chat_id_discovery and wait_for_chat_id_discovery, which handle later steps of the same flow.

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-and-how guidance: pass `deep_link` to render_auth_link, never hand `qr_text` to a link renderer, print it in a fenced block only for terminals, then poll poll_chat_id_discovery with the token, and finally use the chat_id when creating a HITL config. Alternatives and sequencing are spelled out, not 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 write/non-destructive, so the description carries most of the burden. It adds meaningful behavioral context the annotations cannot: the access prerequisite (PROOF account, PROOF_API_KEY env var) and the pre-launch/restart requirement. It also explains the invite-enrollment binding flow. It doesn't describe failure modes or rate limits, keeping it 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?

Well-structured and front-loaded: first sentence defines the entity, second the member seeding, third the workflow, fourth the access prerequisite. Slightly verbose in the 'powering Proof-Me and Approvals-on-Circle' parenthetical, but 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?

For a 5-param create tool with no output schema and minimal annotations, the description covers purpose, workflow sequencing, and the tricky auth/bootstrap requirement. A minor gap is that it doesn't state what the response returns (the created Circle id), but that is a small omission.

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 every parameter including nested member fields. The description adds conceptual framing ('each member's declared channels are stored so they can be invited to enroll') but no syntax or constraints 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 (Create) and resource (Circle) and immediately defines what a Circle is — 'a named group of trusted contacts' — plus its role ('people-primitive powering Proof-Me and Approvals-on-Circle'). This distinguishes it clearly from siblings like update_circle, list_circles, and add_circle_member.

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 agent workflow: create the Circle, then add members with add_circle_member (or seed them here), then invite_circle_member to mint the enrollment deep link. It names the alternative paths and their ordering, leaving nothing 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 (readOnlyHint=false, destructiveHint=false) already tell the agent this is a non-destructive write, and the description adds genuinely new behavioural context: the drill is a real challenge that hits the member, carries a scheduled-safety-check label, and requires a Proof account key that start_login cannot provision. It stops short of describing side effects like notifications sent to the member or rate limits on repeated drills.

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 action and then the access prerequisite, which is the right ordering for an agent that must know the key requirement before calling. Slightly dense jargon and a parenthetical aside ('scheduled-safety-check label') cost a little, but overall it is well-sized with no redundant sentences.

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?

Coverage of what the tool does, its prerequisite, and its non-destructive nature is adequate, but with no output schema the description never says what a drill returns or how to track its progress (e.g. via get_identity_challenge or get_proof_status). For a tool that fires a real member-facing challenge, the missing return/tracking guidance is a real 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 coverage is 100%, so both id and member_id are already documented in the schema, making 3 the baseline. The phrase 'one enrolled member' adds a mild constraint (the member must already be enrolled) but no syntax, format, or behavioural 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: 'Fire an on-demand Proof-Me drill against one enrolled member', clarifying it is a real cross-channel identity challenge rather than a simulated one. It distinguishes itself from the automated daily and monthly drills, though it does not clearly differentiate from neighbouring create-style siblings such as create_identity_challenge or add_circle_member.

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 by framing this as the on-demand complement to the automated daily drill and monthly reinforcement sweeps, so an agent can infer it is the manual/interactive trigger. It also states the prerequisite (a Proof account / PROOF_API_KEY) and explicitly rules out start_login. What is missing is an explicit when-not / alternative-selection rule against sibling challenge 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 cover the safety profile (readOnlyHint=false, destructiveHint=false), but the description discloses far more: first-response-wins semantics, the mandatory encryption requirement, the exact 400 error codes (message_not_encrypted, message_key_mismatch, envelope_missing_approvers), v1 vs v2 envelope selection rules, AAD binding, and the Proof-account/PROOF_API_KEY prerequisite.

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 in one sentence, then separates operational guidance ('Agent usage:') from the encryption rules, which are organized as versioned bullets. It is dense and lengthy, but each section carries necessary failure-mode or format 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?

With no output schema, the description carries the burden well: it states what a confirmation does, what the response lifecycle looks like (approval/denial polling), auth prerequisites, and the encryption contract. 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 coverage is 100%, so a 3 is the baseline, but the description adds real meaning beyond the schema: it clarifies that `message` must be a sealed JSON envelope rather than human-readable text and explains how the envelope version relates to enrolled approvers and the `approver_ek` map. Only `proof_expiry_days` lacks added description (and its allowed values in schema are indirectly referenced in the prose).

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 confirmation request') and immediately names the mechanism (sends approval requests to channels on a referenced HITL config). It is clearly distinguishable from siblings like create_hitl, get_confirmation, and list_confirmations.

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 tells the agent when to use it and what to do on failure: if a 403/'not authorized' occurs, call request_hitl_authorization first, then wait; after creating, poll get_confirmation or use get_confirmation_approval_link. Alternatives and successors are named with unambiguous triggers.

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=false / destructiveHint=false annotations. It discloses billing ('each mint is a billable proof'), a hard failure mode ('a requested lifetime longer than the control proof's remainder is rejected, never truncated'), and the returned shape (publishable token plus DERIVED effective_status/is_valid, consistent with list/get tools).

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 and definition, then progressively adds billing, lifetime behavior, result shape, and access. Every sentence carries information, though the middle section is dense and the access note could be tightened.

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 a nested object parameter, no output schema, and auth requirements, the description covers what is missing elsewhere: return shape, billing implications, the lifetime rejection rule, and the account/API-key prerequisite. An agent has what it needs to decide and call 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 the schema already documents all four parameters, including the scope token format and the expires_in remainder constraint. The description adds only marginal parameter meaning ('rejected, never truncated' on lifetime), so the 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 (create a delegation) and defines what a Proof of Delegation actually is: a control-proven domain authorizing a typed url/purl artifact for capability scopes, returning a publishable signed token. It also scopes the semantics precisely ('the domain's controller authorized this artifact — nothing more'), which lets an agent distinguish it from sibling verbs like list_delegations, get_delegation, and verify_delegation.

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 clear prerequisite in the ACCESS section (needs a Proof account, set PROOF_API_KEY, restart) and an explicit when-not: 'start_login does NOT open this tool.' What is missing is any routing versus close siblings such as create_authorization or create_confirmation, which an agent might otherwise confuse with this minting operation.

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 destructiveHint=true, but the description adds genuinely new behavioral context: the credentials will be exposed in the AI conversation context, which is a material security disclosure an agent should surface. It still omits what happens if credentials already exist for a provider (overwrite vs. error) and what the call returns.

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 and the security warning immediately follows. The ACCESS block is slightly verbose but every clause is actionable; the trailing 'then call this tool again' is a bit awkward yet clear.

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 secret-storing mutation with no output schema, the description covers purpose, auth prerequisites, and the key risk. The remaining gaps — overwrite semantics for an existing provider credential and the return value/shape — are modest but real.

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 schema itself documents both 'provider' (with examples) and the free-form 'credentials' map. The description adds no parameter-level meaning, such as which key names a given provider expects, 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?

The description gives a specific verb and resource ('Store DNS provider credentials') and states the purpose ('for automated domain verification'). However, it does not distinguish this tool from near-siblings like connect_dns_provider, connect_cloudflare, or add_verification_provider, so an agent cannot tell which to pick without opening 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?

It supplies real prerequisite guidance (needs a Proof account; set PROOF_API_KEY and restart, or sign in via start_login) which tells the agent how to unblock the call. It never states when to use this tool instead of the connect_* / add_verification_provider siblings, so alternative 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?

Annotations already flag a non-destructive write, and the description adds real behavioral context beyond them: mandatory post-creation authorization step, channel-specific prerequisites, and an ACCESS note stating a Proof account with PROOF_API_KEY is required and that start_login does NOT unlock this tool. That auth-blocking detail is high-value transparency.

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, then separates "Agent usage" and "ACCESS" into scannable blocks. Every sentence carries distinct, actionable information with no 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 creation tool with nested channel configs, no output schema, and prerequisite steps, the description covers prerequisites and account access thoroughly. It is nearly complete, though it does not state whether the created config is immediately usable or what identifier is returned.

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 documents name, channels, and timeout itself. The description still adds meaning by explaining the telegram chat_id must be obtained via create_chat_id_discovery and included in the channel config, which is guidance the schema cannot express.

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 config") and immediately clarifies what that object contains (channels that receive approval requests plus a default timeout). An agent understands the resource without opening the schema, and it is clearly distinct from the delete_hitl/update_hitl siblings.

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?

Explicit workflow ordering: it names request_hitl_authorization as a required follow-up and create_confirmation as the downstream consumer, and tells the agent to use create_chat_id_discovery first for Telegram channels. This is exactly the when/how-to-use guidance that lets an agent sequence calls correctly.

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 it is a non-read-only, non-destructive write, so the description carries the rest and does so well: it discloses that this is an asynchronous job whose outcome must be polled and enumerates the six terminal states (confirmed, denied, cancelled, failed, expired, revoked). It also flags the access prerequisite (PROOF_API_KEY plus restart) and explicitly notes that start_login does NOT unlock it, which is genuinely useful 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?

Three short, clearly labelled blocks: purpose first, then agent follow-up, then access prerequisites. Every sentence is load-bearing and the most important information (what it creates, how to poll it) 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?

With no output schema, the description compensates by explaining that an ID is returned and must be polled via get_identity_challenge until a terminal state, covering the return-value gap. Access prerequisites and failure states are covered; only the comparison against sibling challenge creators is 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%, so the schema already documents circle_id, member_id and the suspicious_channel default. The description adds conceptual meaning for suspicious_channel (the channel contrast drives the cross-channel check) but no syntax or format 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 and resource ('Create a Proof-Me cross-channel identity challenge (CONFIRM)') plus the scope ('for an enrolled Circle member'), and the second sentence explains the mechanism (approval on a channel different from the suspicious contact's). It does not, however, differentiate itself from closely related siblings such as create_confirmation or create_multi_channel_verification, so the agent still has to infer which challenge creator to pick.

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 'Agent usage' line gives a concrete workflow (poll get_identity_challenge until the status leaves pending) and names the terminal states, which is real next-step guidance. But it never states when to choose this over the other verification/confirmation creators in the sibling list, so the when-to-use decision is only implied by the scenario description.

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=false/destructiveHint=false annotations, it discloses billing semantics (exactly one proof billed at the winning channel's completion, nothing at creation), that losing sibling channels are cancelled, and that most clients hide tool results so the agent must surface actionable content in its own reply. These are the kinds of side effects and UX constraints 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?

It is a long description, but it is front-loaded with purpose before agent instructions, then caveats, then access requirements, and each paragraph carries operative content (billing, link handling, QR verbatim rule, polling target). No sentence is purely decorative, though the length is near the upper bound for a single 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 compensates by documenting the response shape (group_id, channels array, deep_link, sms_message, qr_text) and the follow-up polling tool. Combined with the coverage of prerequisites, billing, and user-visible rendering rules, an agent has everything needed to invoke and complete the flow 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, but the description adds genuine meaning: the channels list is attempted in parallel with first-wins cancellation, and responses carry group_id (vg_<hex>), a channels array with deep_link/sms_message, and qr_text as pre-rendered art rather than an alternate address. That clarifies semantics the schema alone does not.

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 opening sentence names a specific verb+resource (create a multi-channel phone verification) and immediately defines the distinctive mechanism: one phone number challenged over several channels at once with OR/first-wins semantics. That mechanism cleanly separates it from siblings such as create_verification, create_verification_request, and start_2fa without ambiguity.

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 an explicit workflow: pass the returned deep_link to render_auth_link, poll get_multi_channel_verification_status with the group_id, and present the SMS text/number to the user. It also states a when-not (start_login does NOT open this tool) and a precondition (needs a Proof account with PROOF_API_KEY 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 already declare readOnlyHint=false and destructiveHint=true, so the mutation/safety profile is covered. The description adds genuinely new behavioral context that annotations cannot carry: the account/auth prerequisite and how to satisfy it, plus the explicit note that start_login does not unlock this tool. It omits failure behavior, but the auth disclosure is real 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 compact sentences: purpose first, then a clearly delineated ACCESS note. Nothing is redundant and the prerequisite is easy to find. Minor room to be tighter, but no 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 10-parameter, all-optional creation tool with a nested theme object and no output schema, the description covers the field space and the auth prerequisite. It leaves out what the created profile returns (id, primary behavior), which would be the only notable 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%, including the nested theme object, so the schema fully documents every field. The description only restates the field categories at a high level and adds no syntax, default, or interaction meaning beyond what the schema provides. Baseline 3 is correct.

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?

Specific verb 'Create' plus resource 'profile', and it enumerates the optional content categories (display name, bio, avatar, business info, email branding, theme settings). This clearly separates it from update_profile and get_profile, 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?

The ACCESS block gives concrete context on when this tool will actually work (a Proof account plus PROOF_API_KEY) and explicitly rules out a tempting alternative path ('start_login does NOT open this tool'). It stops short of telling the agent when to prefer create_profile over update_profile or set_primary_profile, but the preconditions are clear.

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 safety profile (readOnlyHint=false, destructiveHint=false), yet the description adds substantial undisclosed behavior: the exact return shape, the hosted-flow-with-callbacks model, auth requirements (Proof account, PROOF_API_KEY, server restart), and the UX caveat that the user does not see tool results.

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 a clearly labeled 'Agent usage' block. Every sentence is actionable — the render_auth_link routing, the qr_text warning, the polling step, and the visibility caveat all earn their 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 compensates by describing the return values (deep_link, qr_code, qr_text). Auth prerequisites, follow-up tools, and user-visibility behavior are all covered, so nothing needed to call 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%, so the six parameters are already documented in the schema. The description adds workflow meaning (deep_link/qr_text are outputs, not params) but no extra syntax or constraint detail for channel, phone_number, metadata, etc. 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 phone verification session') and enumerates what it returns (deep_link, qr_code, qr_text). It also distinguishes itself from siblings by noting that start_login does NOT open this tool, so an agent can route correctly.

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 steps (pass deep_link to render_auth_link, then poll with wait_for_session until verified/failed/expired) and an explicit when-not ('Never hand qr_text to a link renderer'). Alternatives and conditions are named rather than inferred.

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 write-but-not-destructive profile is covered. The description adds real value by disclosing the account/auth prerequisite and the login flow that unlocks the tool, but says nothing about what happens after creation (request state, notifications, idempotency, or rate limits).

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 paragraphs: the core action first, then the access prerequisite. No filler or repetition, though the inline asset example is arguably redundant given the schema's own example.

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 action and the auth gate but omits the return shape (request ID, link, status) and any lifecycle context, which an agent needs since no output schema fills that 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% across all 10 parameters, including enums and nested action_context, so the schema carries the semantic load. The description's asset example ({ "type": "email" }) only restates what the schema already documents, so it adds no meaning beyond the structured field. 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 verification request') and clarifies the goal ('ask another user to share verified assets'), which is more than a name restatement. However, it never distinguishes itself from the many near-identical siblings in this namespace (create_verification_request, create_verification, create_authorization, create_confirmation, create_hitl), so an agent cannot tell which creation tool to pick from 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 paragraph gives a genuine prerequisite (needs a Proof account; set PROOF_API_KEY or sign in via start_login, which opens this tool). That is useful when-to-use context, but it is auth onboarding rather than routing guidance — nothing says when to use this over create_verification_request or the other request-creating siblings.

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 write/non-destructive; the description adds substantial beyond-schema behavior: telegram_bot with a LIVE key completes immediately returning status: verified with a proof token and no challenge, whereas pk_test_ stays pending; no qr_text is ever returned; the credential requirement (PROOF_API_KEY, start_login does not unlock it); and that clients hide tool output from the user.

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 usage, behavioral caveats, and the client-visibility note in a logical progression. It is dense and long, but nearly every sentence carries actionable information (deep_link routing, live-vs-test asymmetry, reply-text requirement), so little feels like 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 9-parameter, nested-object tool with no output schema, the description covers the response shape (challenge object, challenge.deep_link, status/proof token), the key branching behavior, auth prerequisites, and what the agent must relay to the user. Nothing an agent needs to call it correctly appears to be 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 schema carries the per-parameter burden and baseline 3 applies. The description goes beyond it by showing worked type/channel/identifier combinations and the cross-parameter constraint that channel must match the asset type, which the schema only loosely hints at.

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?

It states a specific verb and resource ('Create a new identity verification') and describes the flow's scope (asset-based, channel-delivered). It routes to related tools (get_verification, wait_for_verification, render_auth_link) but does not differentiate itself from the many near-name siblings such as trigger_verification, create_verification_request, or create_multi_channel_verification.

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 explicit 'Agent usage' instructions with concrete type/channel/identifier examples and conditional behavior for LIVE vs pk_test_ keys, plus clear next-step guidance (poll get_verification / wait_for_verification for OTP, pass deep_link to render_auth_link for messengers). It stops short of naming when to prefer this over sibling creation endpoints like create_verification_request or trigger_verification.

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. The description adds real behavioral context beyond that: this creates a multi-asset flow, it is gated behind Proof account credentials, and restarting the server is required. It does not mention that the request is likely async (wait_for_request, get_request_proofs siblings exist) or any rate/limit 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?

Two tight paragraphs with the capability stated first and the access precondition second; no filler. The access sentence is slightly awkward ('then call this tool again') but it is front-loaded and 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 10-parameter tool with nested objects, enums, and no output schema, the description covers the credential gate but says nothing about what is returned (request id, per-asset status) or how the caller is expected to follow up. Enough to invoke, incomplete for driving the resulting 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% across 10 parameters with nested asset objects, so the schema already carries the parameter semantics. The description only restates the asset type list and adds nothing about defaults, channel selection, or the action_context/expires_in interactions. 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 multi-asset verification request) and enumerates the seven asset types it covers, so the agent understands scope. It does not name the near-identical siblings (create_verification, create_multi_channel_verification), so sibling differentiation is left implicit.

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 precondition (needs a Proof account; set PROOF_API_KEY and restart) and a negative hint that start_login does not unlock it, which is genuinely useful. However, with ~140 siblings including create_verification, create_multi_channel_verification, create_confirmation and create_authorization, the description never says when this multi-asset form is preferred over those alternatives.

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 annotations: the operation is a soft, recoverable archive even though destructiveHint=true, and it documents the auth prerequisite (Proof account, PROOF_API_KEY, restart required, start_login does NOT unlock this tool). This is exactly the kind of non-obvious behavior an agent needs.

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 soft-delete semantics, then the recovery path, then the access caveat. Every sentence earns its place, though the access block is slightly verbose for a description field.

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, but the description covers the observable result (removal from default listing), the recovery mechanism, and the authentication barrier. Nothing needed 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%, so the single id parameter is already documented with its pattern. The description adds no format or syntax detail beyond what the schema provides, which is the baseline-3 case for a one-param tool.

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 ("Archive a Circle") and immediately disambiguates the implementation: a soft delete that sets status to archived. An agent can distinguish it from hard-delete siblings like delete_profile or delete_domain 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?

Explains the operational consequence (stops appearing in the default list) and the recovery path (list_circles with status="archived"), plus an explicit access precondition. It does not explicitly compare against update_circle, but the soft-delete framing is enough context to select correctly.

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 destructiveHint=true and readOnlyHint=false, but the description adds genuine extra context: the downstream impact on domain verification and the concrete auth prerequisites (PROOF_API_KEY + server restart, or start_login session). It doesn't state reversibility or error behavior, but it goes meaningfully beyond the annotations and does not contradict them.

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 consequence are front-loaded in the first two sentences. The ACCESS block is somewhat verbose and reads as boilerplate, but it is genuinely actionable for an unauthenticated caller.

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 annotations covering the safety profile and no output schema, the description is nearly complete: it covers the action, its consequence, and authentication. Minor gap is the absence of any note on reversibility or failure modes.

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) with 100% schema description coverage ('DNS credential ID to delete'), so the schema carries the semantic load. The description adds no format or sourcing detail for the id, 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?

Specific verb (delete) plus resource (stored DNS provider credential), clearly distinguishable from siblings like create_dns_credential and list_dns_credentials. The added consequence sentence ('Domains using this credential will need new credentials for automated verification') further sharpens what this tool actually does.

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 decision-relevant consequence for deleting (downstream domains lose automated verification), which helps an agent judge whether to call it. It does not, however, explicitly point to alternatives such as revoking or re-creating credentials via create_dns_credential, so it stops 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 mark this destructiveHint=true / readOnlyHint=false, but the description far exceeds them: it discloses irreversibility ('Cannot be undone'), that re-adding the domain will not restore delegations, that some external cleanup may be incomplete (Resend sending domain, _proof TXT record 'where we can'), and that the response returns a manual-removal checklist.

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 destructive consequences before the auth mechanics, and every sentence carries information. The dense parentheticals and the appended access/setup block make it slightly heavier than necessary, but nothing is 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?

No output schema exists, yet the description covers the return value ('the response lists what is left for you to remove by hand'). Combined with the auth prerequisites and full cascade disclosure, 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?

Only one parameter ('id') with 100% schema description coverage, so the schema already carries the semantics. The description only reinforces that the target is 'this domain id' via the 2FA targets list, adding little beyond the structured data — 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 concrete verb+resource ('Remove a domain from the account') and immediately enumerates the cascade: proofs, delegations, domain records, _proof TXT record, Resend sending domain. It also distinguishes itself from revoke_asset by naming that sibling when only proofs need revoking.

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) and the condition selecting it ('Need only a fresh proof? ... which keeps the domain'), and states the preconditions: owner only, start_login session, one 2FA code via start_2fa_for_action with action_type domain_remove and targets [this domain 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?

Annotations only say readOnlyHint=false and destructiveHint=true; the description refines this by clarifying that deleting an unverified attempt revokes nothing, and contrasts it with the case that does revoke proofs and delegations. It also discloses an access prerequisite (Proof account, PROOF_API_KEY, restart) and that start_login does not open this tool, which is behavior no annotation conveys.

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 scope are front-loaded in the first clause, and every clause carries information. The refusal case sentence is a run-on that packs the error code, the revocation consequence, and the alternative tool into one clause, which slightly hurts readability but wastes no words.

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 mutation with no output schema, the description covers the happy path, the refusal path with its error code, the consequence gap versus delete_domain, and the access precondition. Nothing an agent needs in order 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 parameter whose format (24 hex characters) and pattern are already documented in the schema. The description adds no further meaning about 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 (delete a domain verification attempt) and immediately bounds the scope to unverified attempts (pending, verifying, failed). It also names the sibling it must not be confused with — delete_domain, which acts on verified domains — so an agent can pick between them 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 explicit when-it-works (unverified attempts) and when-it-is-refused (verified or needing re-verification, returns domain_verified), plus the alternative route for that case (delete_domain in a start_login session or the dashboard). Both branches and the fallback are covered.

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 genuinely new behavior: deletion is a soft archive that sets status to archived, and it has a downstream consequence (no new confirmations). It also discloses an authentication prerequisite (Proof account, PROOF_API_KEY, restart the server) and explicitly rules out start_login as a path to enabling 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?

The core behavior is front-loaded in one dense sentence, with the access prerequisite separated into its own block so it does not obscure the purpose. Slightly verbose in the access paragraph, but every line 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 single-parameter destructive tool with no output schema and annotations covering the safety profile, the description covers purpose, soft-delete semantics, downstream impact, and auth gating. It leaves minor gaps (fate of in-flight confirmations, reversibility/unarchive path) but is sufficient to call 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 parameter, and schema description coverage is 100%, so the schema already documents 'id'. The description adds no format, source, or lookup guidance for the ID beyond what the schema provides, which is the baseline expectation 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 (delete a HITL config) and immediately clarifies the semantics of 'delete' as archive. This distinguishes it from the similarly-named delete_hitl_keys sibling as well as from create_hitl/update_hitl, since the agent knows exactly which resource and operation is involved.

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?

Usage is implied (you delete an existing HITL config) and the description notes the post-deletion constraint ('cannot be used for new confirmations'), but it never states when to prefer this over alternatives such as delete_hitl_keys or update_hitl, nor any precondition for the target config. The ACCESS note is a prerequisite, not usage routing.

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 the concrete downstream consequence that existing ciphertexts become permanently unreadable and documents the auth requirement. Those are exactly the behavioral details the structured hints do not convey, so it materially adds beyond the 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?

The action and its destructive warning are front-loaded in the first sentence, and the access note is isolated in a separate block. It is efficient; the access paragraph is slightly verbose but every part (env var, restart, start_login caveat) is actionable.

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 annotations and no output schema, the definition covers the safety warning and the auth gate adequately. Nothing critical is missing, though it does not note whether the deletion is idempotent or what the response looks like.

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 hitl_id parameter is documented in the schema. The description adds no syntax, format, or acceptance detail beyond what the schema already provides, 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 (Delete) and resource (the encryption keypair) scoped to a HITL config, so an agent can distinguish it from delete_hitl (which removes the config) and from get_hitl_keys/upload_hitl_keys. The resource is named precisely rather than as a vague 'hitl operation'.

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 (needs a Proof account, set PROOF_API_KEY and restart) and explicitly warns that start_login does NOT unlock this tool, which prevents a common failed-attempt path. It never spells out when to prefer this over delete_hitl or revoke-style alternatives, so it stops short of full when/when-not routing.

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, but the description adds substantial context beyond them: exactly what is revoked/archived/declined/deleted, that history is kept and unlinked, the username is retired for good, the primary-promotion behavior, and that the action cannot be undone.

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?

Long, but front-loaded with the core action and side effects before auth mechanics. Each sentence carries distinct operational information (cascade effects, edge cases, authentication path), though the access/restart paragraph is somewhat boilerplate-heavy.

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 noting the response names the promoted primary project, and it fully covers authentication, failure conditions, irreversible consequences, and edge cases for a single-parameter destructive 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?

Only one parameter with 100% schema description coverage, so the schema does the documentation work. The description references 'this project id' and 'targets [this project id]', which confirms identity but adds no format or constraint 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?

Opens with a specific verb+resource ('Delete a project (profile)') and immediately enumerates the concrete side effects, so an agent can distinguish it from delete_circle, delete_template, or delete_hitl without inspecting 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?

States explicit preconditions and exclusions: the last project cannot be deleted, deleting the primary promotes the oldest remaining, API-key-only callers may delete only an EMPTY project, and 2FA via start_2fa_for_action is required in a start_login session. Alternatives and failure modes (owner_session_required) are named.

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 destructive and non-readonly, but the description adds value beyond them: the deletion is not permanent disappearance of configuration, it reverts the project to the channel/type default, and it requires a Proof account with PROOF_API_KEY configured. It stops short of saying whether the deleted template is recoverable or whether other channel/type templates are unaffected.

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 first sentence is front-loaded and carries the whole purpose and side effect with no waste. The second paragraph is useful but slightly operational in tone (restart instructions) relative to the core semantics.

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 three-parameter tool with full schema coverage and no output schema, the description covers purpose, resulting state, and access requirements. It omits edge-case behavior such as what happens when no custom template exists, 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%, so the baseline is 3, but the description ties the parameters to an outcome: channel + message_type define which template is reverted to default, and profile_id is the sub-account/project scope. That adds a small amount of semantic meaning over the schema's field-level text.

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 (a sub-account's custom template) and goes further by naming the resulting state: the project reverts to the default template for that channel and message type. This distinguishes it cleanly from update_template, get_template, and list_templates 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?

Usage is implied rather than stated: the agent can infer this is the tool to remove a customization, but there is no explicit when-to-use/when-not guidance or comparison to siblings such as update_template. The ACCESS paragraph is a useful prerequisite (account type, PROOF_API_KEY) but addresses setup, not tool selection.

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, so the description carries the rest and does so well: it discloses the 10,000-record cap and the authentication prerequisite with a negative instruction about start_login. What it omits is how results are delivered (file path, stream, or URL) and what happens when the cap is exceeded.

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, capability, and the record cap are front-loaded in one tight sentence, and the access prerequisite is cleanly separated. The budget is well spent, though the restart instruction is operational noise an agent cannot act on within 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?

With no output schema, the description should say what an export returns and how to retrieve it, which it never does; pagination behavior at the 10,000 cap is also unstated. Access and filtering are covered adequately, but a data-export tool leaves the delivery mechanism 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?

With 100% schema description coverage and enums on format and status, the schema already documents every parameter including ISO 8601 date formats. The description only restates format and filter concepts, adding no syntax or default information beyond what the schema provides, 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?

It names a specific verb and resource ('Export authorizations'), states the output formats (CSV or JSON), and lists the filter dimensions, so an agent knows exactly what the call produces. It does not, however, distinguish itself from the sibling 'export_data' or explain why one would export rather than call 'list_authorizations'.

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 a genuine prerequisite (a Proof account, PROOF_API_KEY set, server restart) and even rules out a wrong path by stating start_login does not unlock this tool. But there is no guidance on when to choose this over 'list_authorizations' or 'export_data', nor any exclusion criteria for the filters.

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, so the description carries the behavioral burden and does so richly: background preparation, email/login-channel delivery, a link that only works while signed in, the tool never returning data itself, one export per 24h (no limit during deletion scheduling), and 7-day retention. This is exactly the kind of context annotations cannot express.

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 auth prerequisite, then polling/limits — a logical order with little waste. The trailing ACCESS block partly repeats the start_login guidance already given earlier, which is the only 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 an async, owner-gated export with no output schema, the description covers the full lifecycle an agent needs: how to start, how to poll, what is returned (nothing — data arrives by email), auth requirements, and rate/retention constraints. 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?

With 100% schema coverage on a single optional param, the schema already documents export_id with its pattern. The description's 'Pass export_id to read one export's status' restates the schema rather than adding format or edge-case 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 specific verb+resource ('Export a complete copy of your account's data') and anchors it to GDPR Articles 15 and 20, which immediately distinguishes it from sibling listing tools like export_authorizations. An agent can tell what this 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?

Explicitly covers when to use it (owner-only data export), the prerequisite auth path (start_login; API-key-only connections refused with user_session_required), the call-again-to-poll pattern, and the 24h/7-day limits. Alternatives and exclusions are stated, not inferred.

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 profile is covered. The description adds real context beyond that: it operates on pending requests only and requires a Proof account via PROOF_API_KEY or start_login. It stops short of describing the resulting expiration value or whether extension can be repeated.

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 sentence is front-loaded and wastes no words. The ACCESS block is somewhat verbose and slightly repetitive ('then call this tool again'), but it conveys actionable setup 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?

For a simple one-parameter mutation tool with annotations covering the safety profile and no output schema, the description covers purpose, precondition, and auth setup adequately. The only real gap is the resulting expiration behavior, which is minor here.

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 parameter meaning. The description adds nothing about parameter format or constraints, which is the expected baseline-3 outcome when the schema does the work.

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 (extend) and resource (the expiration time of a pending verification request), which an agent can clearly distinguish from siblings like cancel_verification_request or get_verification_request. It does not explicitly name the sibling it contrasts with, so it lands at 4 rather than 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 'pending' qualifier implies the tool only applies to still-pending requests, giving implicit state guidance, but there is no explicit when-to-use vs alternatives (e.g., when to extend versus cancel or re-create). Usage is implied rather than 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?

With readOnlyHint already covering the safety profile, the description still adds substantial behavioral context: polling cadence, the meaning of each terminal state, and the requirement that the caller's reply text must surface the link/SMS before polling. It does not quantify rate limits or backoff, but the cadence guidance goes well beyond the annotation.

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 states, then usage, then auth access. Every paragraph is functional, though the 'Agent usage' block runs somewhat long relative to a single-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 read-only single-param tool with no output schema, the description compensates well by enumerating the returned states and stating the Proof account/API-key prerequisite. It stops short of situating itself against the sibling set (verify_2fa, wait_for_2fa), which is the remaining completeness 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% for the single session_id parameter, so the schema already carries the full parameter definition. The description adds only the tie-in to start_2fa ('a challenge you created') and no format or provenance details, so baseline 3 is correct.

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 ('Check the status of a 2FA session by session ID') and enumerates the possible outcomes (completed, pending, expired). An agent can distinguish this from get_verification or get_proof_status 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 clear when-to-use context ('Poll this after calling start_2fa. Check every few seconds') and maps terminal states to next actions ('expired' → restart with start_2fa). It never mentions wait_for_2fa, a sibling that appears to serve the blocking alternative to polling, which leaves one routing decision 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 readOnlyHint=true, and the description adds meaningful context beyond that: it requires a Proof account, PROOF_API_KEY, and a restart or start_login flow before it will work. It does not describe polling behavior, terminal states, or rate expectations, which is a minor gap for a status-check 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?

Front-loaded one-line purpose followed by a clearly labeled ACCESS block; every sentence earns its place. The flow instruction is slightly procedural but genuinely useful for invocation.

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 simple read-only status tool the coverage is close to adequate, and annotations cover the safety profile. However, with no output schema, the description says nothing about what status values or fields are returned, which an agent polling for completion would benefit from.

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 required parameter with 100% schema coverage, so the schema already carries the semantics. The phrase 'by session ID' merely restates it without adding format, provenance, or validity details (e.g., where the session ID comes from is only implied by the start_login hint).

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 email addition') and scopes it to a session ID, which distinguishes it from siblings like start_add_email and verify_email_otp. It stops short of explicitly naming the sibling it is not (e.g., get_add_phone_status or verify_email_otp).

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 workflow context: the session is opened by start_login and the caller should 'call this tool again' after authenticating. It clarifies when the tool becomes usable, though it never states when NOT to use it or which alternative covers a completed/failed addition.

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 provide readOnlyHint=true, so the description usefully adds the polling contract ('until terminal state') and the auth prerequisite (PROOF_API_KEY or a session opened by start_login). It doesn't describe the returned status values or the response shape, which remains undisclosed.

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 and the polling directive is adjacent. The UX aside about showing the user the link is somewhat tangential but genuinely actionable, and the ACCESS block 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?

For a read-only polling tool with no output schema, the description covers auth and polling cadence but never explains what statuses or terminal states an agent should expect, leaving the return contract implied.

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?

With one parameter and 100% schema description coverage, the schema already carries the semantics of session_id. The description's phrase 'by session ID' adds nothing beyond what the schema 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+resource+scope: 'Check the status of an in-progress phone addition by session ID.' This clearly distinguishes it from the sibling start_add_phone (initiates) and from get_add_email_status (email variant).

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?

Tells the agent to 'Poll until terminal state,' implying this is called after start_add_phone while the flow is in progress. It also routes auth setup via start_login. It stops short of explicitly naming start_add_phone as the prerequisite or stating what the terminal states are.

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 readOnlyHint, it discloses non-obvious traits: counts are aggregates only with no recipient identifiers, counts include the key plus every key it replaced (replaced_key_ids), and there is an account/self-scoping authorization rule. The ACCESS paragraph also documents auth requirements and the start_login fallback.

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 returns, then covers scope and access in a separate paragraph, with zero filler sentences. It is somewhat dense but every clause carries information, so it stays appropriately sized.

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 returned metrics and attribution fields, and it states the auth/scope constraints an agent needs. Nothing required to select or invoke the 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?

Schema description coverage is 100%, so both parameters (id, environment) are already documented in the schema. The description reinforces the id's meaning ('for a given key id') but adds no syntax or default 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+resource (per-API-key usage for a given key id) and enumerates the returned breakdowns: verification counts by type/channel/status, request/confirmation/authorization totals, and attribution context. This clearly distinguishes it from siblings like get_usage, get_platform_summary, and get_self_api_key.

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: scoped to the authenticated account, and an API-key caller may read only its own key, plus the PROOF_API_KEY / start_login prerequisites. However, it never explicitly names when to prefer this over get_usage or get_self_api_key, so no exclusion/alternative guidance is present.

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, so the description adds real value: it identifies the tool as a read of a single asset, lists what is returned, and surfaces an account/auth prerequisite plus a routing warning that start_login will not unlock it. It stops short of disclosing error behavior for unknown IDs or rate limits.

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: return contents first, then the access constraint, front-loaded and waste-free. The auth paragraph is slightly long relative to the tool's simplicity but each clause 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 correctly compensates by enumerating the returned fields, and it supplies the account prerequisite an agent needs before calling. The only gap is what happens on a missing/unauthorized ID, which is minor for a simple single-resource read.

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 ('Asset ID'), so the schema already carries the semantics. The description adds no format, source, or lookup guidance for the ID beyond what the schema states – the 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 ('Get a single verified asset by ID') and enumerates the returned fields (type, value, status, verification timestamps). The 'single ... by ID' phrasing implicitly separates it from list_assets and revoke_asset, 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?

The description gives a strong prerequisite ('needs a Proof account. Set PROOF_API_KEY and restart this server') and clarifying exclusions ('start_login does NOT open this tool'), but it never says when to reach for get_asset versus list_assets, get_profile_assets, or get_verified_user. 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?

The readOnlyHint annotation already establishes safety, but the description adds meaningful context: it returns status and usage statistics, and requires a Proof account plus PROOF_API_KEY to invoke. It stops short of covering error behavior or permission scopes, so it is strong but not exhaustive.

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: purpose and return value first, then access requirements. Every sentence carries useful information, and nothing is buried or redundant.

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 simple single-parameter read tool with no output schema, the description covers purpose, return highlights, and access prerequisites. It does not detail status values or usage-statistics fields, but it is otherwise sufficient for correct invocation.

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 already documented as 'Authorization ID'. The description only repeats 'by ID' without adding format, validation, or lookup 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 specific verb and resource ('Get an authorization by ID') and distinguishes itself from list/create/revoke siblings through the 'by ID' scope. It also describes what the response contains: current state, status, and usage statistics.

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 clear access precondition: a Proof account with PROOF_API_KEY set and server restart. It also explicitly warns that start_login does NOT open this tool, which is a useful when-not note, but it does not name alternative retrieval tools such as list_authorizations.

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, but the description adds real behavioral detail: the return shape (members plus per-member channel presence booleans) and a deliberate security constraint ("an identifier is NEVER returned — SEC-PM-006"). The auth prerequisite is also disclosed, which is exactly the kind of 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?

Front-loaded with the core action, followed by return contents and then access requirements, so the most important information comes first. The SEC-PM-006 reference and restart instructions add length but each earns its place; slightly dense for a single-parameter read.

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 shoulders the return-value burden by naming the members collection and the channel-presence booleans, plus the identifier omission. Auth setup and the sibling exclusion round it out, leaving only deeper field-level detail 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% and the single id parameter already carries its 24-hex-char pattern in the schema. The description only restates "by ID" without adding format, sourcing, or lookup guidance beyond what the schema provides, 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 ("Get a Circle") and scopes it to a single record via "by ID", which cleanly separates it from list_circles, create_circle, update_circle and delete_circle without opening any schema. It also previews the payload (members, per-member channel presence booleans), so an agent knows what kind of retrieval this is.

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 clear operational context for when the tool will work ("needs a Proof account... Set PROOF_API_KEY and restart this server") and gives an explicit exclusion relative to a sibling: "start_login does NOT open this tool." It stops short of stating when to prefer this over list_circles, so it is context-rich but not fully alternative-routing.

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 safety is covered. The description adds value beyond that by disclosing the auth requirement and the return payload (status, response, proof token), which an agent needs to know before calling and interpreting results.

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 with the core purpose front-loaded and the access caveat clearly separated. The ACCESS note is slightly verbose but every clause is operative; nothing is 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 read-only single-ID fetch with no output schema, the description supplies both return content and the auth prerequisite, which is enough for correct invocation. Only a pointer to related tools (e.g. wait_for_confirmation) 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% with a single described 'id' parameter, so the schema carries the semantics. The description repeats 'by ID' without adding format, source, or lookup guidance, warranting the baseline 3.

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 ('a confirmation') scoped 'by ID', which distinguishes it from sibling list_confirmations, create_confirmation, and get_confirmation_approval_link. It stops short of naming those siblings explicitly, so differentiation is inferred rather than stated.

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 precondition (needs a Proof account, set PROOF_API_KEY and restart) and rules out a tempting wrong path ('start_login does NOT open this tool'). It does not clarify when to prefer this over get_confirmation_approval_link or wait_for_confirmation, but the access guidance is concrete and actionable.

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 context beyond the annotations: the link expiry inherits the confirmation timeout, the tool only functions for pending confirmations, and it requires a Proof account with an env-var/restart setup. Annotations only say readOnly=false and destructive=false, so this prose carries real behavioral value; it does not state whether regenerating invalidates a prior link.

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 capability is front-loaded in the first sentence, followed by expiry and eligibility, then access setup. Every sentence carries information, though the access paragraph is slightly verbose 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?

No output schema exists, yet the description never says what the call returns (a URL string? an object with expiry?). For a link-generation tool that is the primary thing an agent needs. Expiry and access coverage are good, so this is adequate but with a clear 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 coverage is 100% and there is a single 'id' parameter fully documented in the schema, so the baseline is 3. The description adds no format, lookup, or constraint detail about the confirmation ID beyond what the schema already provides.

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 ('Generate a fresh approval link') and narrows scope to 'a pending confirmation', which separates it from the nearby get_confirmation/create_confirmation/list_confirmations siblings. It does not name an alternative explicitly, 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 a clear precondition ('Only works for pending confirmations') and an explicit access prerequisite (Proof account, PROOF_API_KEY, restart), including a negative warning that start_login does not unlock this tool. No explicit when-to-use-instead-of-sibling guidance, so not 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?

Annotations only declare readOnlyHint=true, so the description carries the rest: it discloses the required auth context, the inability to authenticate via API key alone, and the login flow ordering. It does not describe pagination or the response shape, but for a no-argument self-read tool that gap is minor.

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 the sibling routing are front-loaded in the first two sentences, which is the right ordering. The ACCESS block, however, restates the start_login/wait_for_login sequence already given above, adding length without new 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 read-only, zero-parameter tool with no output schema, the description supplies everything an agent needs: what it returns at a high level, the mandatory login prerequisite, and the authenticated-vs-API-key access distinction. No material gap remains.

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?

Zero parameters, so the schema baseline is 4. The description correctly implies no inputs are needed and adds no contradictory parameter guidance.

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?

Specific verb+resource ("Get the signed-in user's account details, plan and settings") with the subject-scope (signed-in user, not the API key's account) made explicit. It names the siblings that cover adjacent cases (get_self_api_key, get_settings), so an agent can distinguish it 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?

Explicit when-to-use (a login session is required) and when-not-to-use ("An API key alone cannot read this"), with named alternatives for the excluded case. The prerequisite call sequence (start_login then wait_for_login) is spelled out, leaving nothing 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 already declare readOnlyHint=true, and the description goes beyond that with non-obvious access context: it needs a Proof account, PROOF_API_KEY must be set with a restart, and start_login will NOT unlock it. That auth-disclosure is genuinely useful and not derivable 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?

Purpose is front-loaded in the first sentence, and the access caveat is isolated in its own labeled paragraph. No filler, though the second paragraph is slightly long for a single 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 zero-parameter read-only list tool with no output schema, the description covers purpose, scope, and access prerequisites. Nothing an agent needs to invoke it correctly is missing; only an explicit sibling comparison would push it higher.

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 per the rubric. Schema coverage is 100% and there is nothing param-related the description needs to compensate for.

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 defines what 'default' means ('built-in templates a project sends when it has no custom template of its own'). This meaningfully distinguishes it from siblings like list_templates and get_template, though it never names them.

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