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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the meaningful state model (member starts pending, Telegram chat id is bound later via the enrollment deep link) and the auth gate. It does not mention rate limits, duplicate-name behavior, or whether the WhatsApp phone must match at enrollment time, leaving a few behavioral questions open.

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, then workflow, then access, which is the right order for an agent. There is mild redundancy between 'the Telegram chat id is captured later when the member taps the enrollment deep link' and the 'mint the single-use enrollment link the member taps to bind their messenger identity' sentence in the usage note.

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 three-parameter mutation with an output schema already present, the description covers the full lifecycle: prerequisite auth, what state the member lands in, and the required follow-up call. 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 the baseline is 3; the description still adds meaning by framing name as the sole identity signal and the phone as 'pre-declared' rather than verified, and by situating the chat id as a later-bound value not passed here. It stops short of explaining format edge cases (e.g., name collisions), which the schema handles only via min/max length.

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') plus the key scoping detail that the member is pending and identified by name, with an optional pre-declared WhatsApp phone. This clearly separates it from sibling tools like invite_circle_member (mints the link), add_circle_member_channel (binds a channel), and create_circle_member_drill (test 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 an explicit sequencing rule ('after adding a member, call invite_circle_member to mint the single-use enrollment link') and a negative case ('start_login does NOT open this tool'), which prevents a plausible wrong path. Prerequisites (Proof account + PROOF_API_KEY) are spelled out with the remedy.

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 non-read-only and non-destructive, which is thin; the description adds real context: the 409 conflict when the channel type already exists, and that identifier format is validated server-side rather than client-side. It does not say whether the call is idempotent or what permissions beyond a Proof account are required, 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?

The functional sentence and the 409/format caveat are front-loaded, and the ACCESS block is clearly separated. The auth paragraph is slightly verbose for an environment variable that is documented elsewhere, but the 'start_login does NOT open this tool' line earns its place by preventing a common dead end.

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

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

An output schema exists, so return values need not be explained, and the description covers the mutation, the duplicate-error case, identifier validation, and the auth gate. The main remaining gap is the interaction with sibling member tools (e.g. whether the member must already exist), which is left unstated.

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

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

Schema description coverage is 100%, with every parameter documented including the channel enum and the leading-'+' E.164 requirement. The description restates the identifier-format rule but adds no new syntax or constraints beyond what the schema already 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?

The description opens with a specific verb and resource: 'Declare a channel for a Circle member.' Combined with the channel enum (telegram/whatsapp) referenced later, an agent can distinguish this from list_circle_member_channels and remove_circle_member_channel 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?

It gives a hard prerequisite (Proof account, PROOF_API_KEY set, server restart) and explicitly warns that start_login does not unlock this tool, which is genuinely useful routing info. However, it never states when to use this versus add_circle_member, invite_circle_member, or the discovery tools that produce a Telegram chat id, so the alternative selection is left implicit.

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

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

The annotations only tell the agent this is a non-read-only, non-destructive mutation; the description adds the auth/session prerequisite and the fact that the domain is being registered for a later ownership check. It does not disclose idempotency behavior, whether a DNS record is created immediately, or what happens on duplicate domains.

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

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

Two short blocks: the purpose sentence first, then access prerequisites. The ACCESS block is slightly verbose given it restates the restart requirement, but nothing is wasted and the key action 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 an output schema present, return values need no explanation, and the auth prerequisite is covered. Remaining gaps are modest: the description doesn't say what the natural next step is (verification) or how this differs from the DNS-provider connection siblings.

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 each of the four parameters already has a description, so the baseline is 3. The prose names the two optional concepts (email sending intent, verification method) but adds no meaning beyond the schema — notably nothing about profile_id or how verification_method interacts with the account's DNS provider.

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

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

The description states a specific verb and resource — 'Add a new domain to verify ownership' — plus the optional knobs (email sending intent, verification method). It implicitly separates itself from follow-up siblings like verify_domain or start_domain_verification, but never names an alternative such as connect_cloudflare or connect_dns_provider, which is arguably the closest decision point.

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

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

The ACCESS paragraph gives a real prerequisite workflow: a Proof account, PROOF_API_KEY, or signing in via start_login before retrying. That is genuine when-to-use context. However there is no guidance on when to pick this over automated DNS-connection tools, or on what to do if the domain already exists.

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 the mutation as destructive, and the description meaningfully adds that the supplied credentials will be exposed in the conversation context — a non-obvious side effect an agent must surface to the user. It also documents the auth path (PROOF_API_KEY or start_login). It stops short of saying what happens to existing providers on the domain or whether the new provider replaces anything.

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

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

The core purpose and precondition are front-loaded in the first sentence, and the exposure warning follows immediately. The ACCESS paragraph is slightly verbose with restart instructions, but each sentence is actionable 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 annotations, a full-coverage schema and an output schema already present, the description only needs to cover preconditions, auth and side effects — which it does. The remaining gap is sibling disambiguation among the many DNS/credential tools.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by clarifying that the credentials object is passed inline and becomes visible in context, which affects how the value should be handled. It adds nothing about the 'provider' identifier domain (e.g. valid provider strings), but the schema already carries that.

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 DNS provider for verification) plus a meaningful precondition that the domain must already be verified. However, it never distinguishes itself from close siblings such as connect_dns_provider or create_dns_credential, so an agent still has to guess which of the DNS-credential tools is correct.

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 'already-verified domain' constraint is genuine when-to-use guidance, and the ACCESS paragraph explains how to become authorized. But there is no when-not guidance and no comparison to the several closely overlapping DNS credential tools in the sibling list, which is the main selection risk here.

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 mutation profile is known; the description adds real context on top — creator-only authorization, pending-only eligibility, and the API-key/login prerequisite. It stops short of saying whether a cancelled request can be revived or re-created, which matters for a destructive 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?

Two short blocks, action first, access second; nothing is padded. The phrasing 'a session opens this tool' is slightly awkward but the instruction sequence (set key or start_login, then retry) is still readable.

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?

An output schema exists so return values need no explanation, and the auth flow plus eligibility rules are covered. The remaining gap is sibling disambiguation against cancel_verification_request, which an agent must resolve before calling this correctly.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as 'Verification request ID to cancel'. The description adds no format, prefix, or lookup guidance beyond that, so the schema does all the work — 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 ('Cancel a pending verification request') plus an authorization scope ('Only the creator can cancel'). It does not, however, distinguish itself from the near-identically named sibling cancel_verification_request, leaving the agent to guess which cancel tool applies.

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

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

Gives concrete preconditions for use: the request must be pending and the caller must be its creator. The ACCESS paragraph further explains how to become authenticated before retrying. What is missing is any guidance on when to choose this over cancel_verification_request, the obvious alternative in the sibling list.

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 context beyond that: the state constraint that only pending requests qualify, plus an explicit authentication prerequisite (PROOF_API_KEY + restart) and a note that start_login does not grant access. It stops short of saying whether the cancellation is reversible or what happens to proof data.

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 its precondition are front-loaded in two tight sentences; the access block follows and is clearly separated. The access note is slightly verbose but earns its place as an operational prerequisite.

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

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

An output schema exists, so return values need no explanation, and annotations carry the destructive profile. The description fills the remaining gaps an agent needs: the pending-only precondition and the API-key requirement.

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

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

Schema coverage is 100% with a single 'id' parameter already documented as the verification request ID. The description adds no further meaning about the identifier, 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?

Names a specific verb and resource ('Cancel a pending verification request') and adds a scope qualification. An agent can identify the operation immediately, though it does not explicitly distinguish itself from the nearby cancel_user_request sibling.

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

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

Provides one concrete precondition ('Only pending requests can be cancelled'), which tells the agent when the call will succeed. It does not name alternatives for non-pending requests or state what the caller should do instead, leaving the routing guidance incomplete.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds information the annotations do not carry: the tool operates on stored credentials and requires a Proof account, configured either via PROOF_API_KEY plus a server restart or via start_login. It does not explain what a negative result looks like (no credentials vs. insufficient permissions), but that is largely the output schema's job.

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 sequencing guidance are front-loaded in the first two sentences, and the ACCESS block is clearly separated. The access paragraph is slightly long relative to the tool's simplicity but is genuinely necessary setup 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 one parameter, an output schema, and a readOnly annotation, the definition covers the essentials, and the auth/bootstrap instructions are a real addition for a tool that will otherwise fail silently for unauthenticated agents. Only the mapping from a failed check to a next action is left implicit.

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

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

Schema coverage is 100% and the single parameter 'id' is documented there as the domain ID. The description's phrase "a domain" adds 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?

The first sentence gives a specific verb and resource: it checks whether stored DNS credentials have access to a given domain, which distinguishes it from verify_domain_with_credentials and trigger_verification. It stops short of naming the sibling it is not, so an agent must infer the boundary.

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

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

"Use before triggering verification to confirm the credentials work" gives an explicit sequencing condition that ties it to trigger_verification. There is no explicit when-not guidance or named alternative for the case where credentials are absent (e.g., create_dns_credential).

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=true, the description discloses the Proof account requirement, two authentication routes, the need to restart the server after setting the API key, and the need to retry after login. These are meaningful invocation behaviors, although no additional polling or progress-state semantics are provided.

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 is front-loaded in one clear sentence, followed by a separate, practical ACCESS paragraph. Despite slightly awkward phrasing in "a session opens this tool," the text is compact and each part serves invocation or authentication.

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 read-only status tool with an output schema, the purpose, DNS-progress scope, and authentication requirements provide enough information to invoke it successfully. Explicit workflow placement and a source for the domain ID would make the definition more complete.

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

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

Schema description coverage is 100%, and the sole required id parameter is already documented as a Domain ID, so the baseline is 3. The description adds no information about the ID's format or how to obtain it, such as through list_domains.

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 gives a specific verb and resource: checking a domain's email sending setup status, with DNS record configuration progress as a useful scope detail. It does not explicitly distinguish this status check from siblings such as setup_domain_email or check_domain_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?

The description establishes the context of monitoring email setup and DNS configuration progress, and it gives concrete guidance for gaining access through PROOF_API_KEY or start_login. It does not explain where this fits in the workflow, such as checking after setup_domain_email, or when a different domain-status tool is preferable.

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

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

The annotations mark this as non-read-only and non-destructive, and the description explains why: it triggers a network DNS/HTTP check as a side effect and returns an updated status rather than cached data. The access paragraph adds credential requirements and a restart step, which the annotations cannot convey.

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

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

Two tight sentences deliver purpose and side effect, then a clearly separated access block. Every sentence carries information; only slight redundancy between 'check the status' and 'returns the updated status'.

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?

An output schema is present, so return values need no explanation, and the critical operational prerequisite (Proof account, PROOF_API_KEY, server restart) is stated. For a one-parameter tool this is essentially complete; only comparison to sibling verification tools 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% and the single 'id' parameter is already described as the 'Domain verification ID'. The description reinforces that the ID refers to a pending verification rather than a domain, but adds no syntax or format 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 ('Check the status') and resource ('pending domain verification') and adds that it triggers a live DNS/HTTP check, which separates it from passive readers like get_verification or get_domain. It does not name a specific sibling as the alternative, so it falls short of full sibling differentiation.

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

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

The phrase 'pending domain verification' implies usage scope (only after a verification was started), and the ACCESS paragraph usefully explains the account prerequisite and that start_login will not unlock this tool. However, it never says when to prefer this over verify_domain, trigger_verification, or start_domain_verification, which are close 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?

Beyond the annotations, the description adds meaningful operational context: it requires a Proof account, can be authenticated via PROOF_API_KEY, and otherwise needs a login session from start_login. It does not fully explain the side effects of 'triggering' a check, but the auth and timing details materially help correct invocation.

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

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

The description is compact and front-loads the purpose and timing before the access note. Every sentence carries useful information, though the phrase 'a session opens this tool' is slightly awkward and could be clearer.

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 tool with an output schema and annotations, the description covers the essential purpose, call timing, and authentication prerequisite. The main remaining gap is sibling disambiguation, which is more a usage-guideline issue than missing core context.

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

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

Schema coverage is 100% for the single session_id parameter, so the schema already documents its meaning as the domain verification session ID. The description does not add parameter-level detail beyond indirectly referring to a session, which is acceptable given the high schema coverage but not enriching.

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

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

The description states a specific verb and resource: 'Trigger a check on the domain verification challenge.' It is clear what the tool does, but it does not distinguish this user-domain check from the similarly named sibling check_domain_verification or from 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?

It gives a concrete trigger condition: call after placing the DNS record or HTTP file. It also explains the Proof account prerequisite. However, it does not name alternatives or clarify when to use this instead of sibling verification-status or domain-verification 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 already declare readOnlyHint=false and destructiveHint=false, so the mutation/non-destructive profile is covered. The description adds value beyond that by disclosing the authentication prerequisite and the session bootstrap path via start_login -- information an agent cannot get from the schema. It omits what happens when the username is already taken or whether the claim is idempotent, so it is good but not complete.

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

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

Two short blocks: purpose plus constraints first, then a clearly labelled ACCESS prerequisite. It is front-loaded and easy to scan. The constraint sentence duplicates the schema pattern, a minor redundancy that costs it the top score.

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 annotations and an output schema already supplied, the description covers what is claimed, the validation rules, and the exact authentication path needed to invoke it. Nothing essential to a correct first 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?

Schema coverage is 100% and the single parameter already carries the exact constraint text (3-30 chars, alphanumeric and underscores) plus a regex pattern. The description restates that rule verbatim rather than adding meaning such as case sensitivity, reserved names, or uniqueness-check behavior, 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 states a specific verb and resource -- 'Claim a unique username for the authenticated user's public profile' -- which is unambiguous and does not overlap with any sibling such as update_my_profile or get_profile. It stops short of explicitly contrasting with those siblings, but the operation is distinct enough that no agent would confuse 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?

It gives real preconditions: the caller must have a Proof account, either via PROOF_API_KEY or by opening a session with start_login, and names the recovery path ('then call this tool again'). It does not address alternatives such as updating an existing username or whether re-claiming is permitted, which keeps it out of the top band.

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, and the description adds genuinely useful context: the Proof account/PROOF_API_KEY requirement and that a session from start_login unlocks the tool. It says nothing about code expiry, lockout after wrong attempts, rate limits, or the effect of a successful confirmation, which are the remaining behavioral gaps.

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 action first, then the access prerequisite. No filler, though the access block is somewhat operational rather than tool-specific.

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?

The tool is simple (2 required params, output schema present, annotations present), and the description covers the action plus the auth prerequisite that would otherwise block an agent. Failure-mode behavior is the only meaningful 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 coverage is 100%, with both 'id' (Domain ID) and 'code' (verification code from the email) documented in the schema itself. The description only restates that the code comes from the corporate email and adds no format, length, or sourcing 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?

The description states a specific verb and resource ('Confirm domain email verification') and specifies the mechanism ('by submitting the code sent to the corporate email address'), which separates it from start_domain_email_verification (which initiates the send) and resend_domain_email. It does not explicitly name those siblings, so it falls short of the top mark.

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 by the flow ('then call this tool again' after a session opens), and the ACCESS paragraph gives a real prerequisite. However, it does not say when to call resend_domain_email instead if the code expired, nor what to do on a rejected code, so alternatives and exclusions are absent.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the bar is lower, and the description does add genuine value: a warning that the API token will be visible in conversation context, plus the auth/session prerequisite. What it does not disclose is the destructive dimension that the annotation flags, i.e. what happens to existing DNS records on the domain when a new token is connected, or whether the token is persisted.

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 clause, followed by a short security note and a compact ACCESS block. Nothing is padded, though the note and access block could be tightened into a single prerequisites sentence without loss.

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?

An output schema exists, so return values need no explanation, and the auth setup is well covered. The gap is against tool complexity: this is a destructive mutation touching live DNS, yet the description never says what is replaced or whether connecting again overwrites prior configuration, nor how it differs from the other connect_* tools.

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

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

Schema description coverage is 100%, with 'id' as Domain ID and 'api_token' constrained to a Cloudflare token with DNS edit permissions, so the baseline of 3 applies. The prose adds only that the token is sensitive in context, not additional meaning about the parameters themselves.

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 Cloudflare API token to a domain for automated DNS record management.' That is concrete and unambiguous about the outcome. However, it never distinguishes itself from the sibling connect_godaddy and connect_dns_provider tools, so an agent must infer which one to pick from the provider 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 ACCESS paragraph gives real contextual guidance: a Proof account is required, PROOF_API_KEY must be set, or the agent should call start_login and then retry this tool. That is a concrete prerequisite chain the agent can act on. It stops short of any exclusion guidance (e.g. when to prefer connect_dns_provider instead), so it does not reach 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 already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: credentials will be exposed in the AI conversation context, and the call will fail until authentication is established. It does not describe what DNS changes are actually made on the provider side, which is the remaining gap.

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

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

Two tight sections — what it does, then an explicit ACCESS block — with the credential-exposure warning front-loaded where it is most likely to be read. Minor redundancy in "then call this tool again," which is already implied by the retry instruction.

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

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

For a destructive three-parameter mutation with a nested credential object, the definition covers the two things an agent most needs to avoid a blind failure: the auth precondition and the credential-visibility side effect. An output schema exists, so return values need no explanation; only the downstream DNS effect is left 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%, so id, provider, and credentials are all documented structurally. The description's phrase "provider-specific credentials" reinforces that the credentials object is free-form and varies by provider, but adds no format, required-key, or example 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?

The description opens with a specific verb and resource: "Connect a generic DNS provider to a domain using provider-specific credentials." The word "generic" implicitly separates it from the provider-specific siblings connect_cloudflare and connect_godaddy, but those siblings are never named, so an agent must infer the split 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?

It gives clear operational context: a Proof account is required, and it spells out two paths (PROOF_API_KEY + restart, or start_login followed by a retry). What it does not do is state when to prefer this over connect_cloudflare or connect_godaddy — no explicit exclusion or alternative routing 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 already flag readOnlyHint=false and destructiveHint=true, and the description adds two things they cannot convey: that the API key and secret will be exposed in the AI conversation context, and the exact auth flow for obtaining access. The one gap is that it never explains what the destructive flag means here – whether existing DNS records are overwritten.

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

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

Purpose and the secret-exposure warning are front-loaded in the first two clauses, with access instructions following. Every sentence carries information, though the ACCESS block reads as internal shorthand slightly compressed for a first call.

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 an output schema present, return values need no explanation, and the description covers the secrecy and auth prerequisites that dominate calling this tool. What remains missing is the consequence of the destructive hint on existing DNS configuration.

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?

All three parameters are documented at 100% schema coverage (id as Domain ID, api_key, api_secret), so the schema carries the semantics. The description only clarifies that the credentials are GoDaddy-specific, adding little beyond the schema.

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

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

States a specific verb and resource ('Connect GoDaddy API credentials to a domain') plus the payoff ('automated DNS record management'), which lets an agent separate it from connect_cloudflare or connect_dns_provider. It does not explicitly name those alternatives, so it falls short of full sibling differentiation.

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

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

Gives concrete preconditions and a recovery path: needs a Proof account, set PROOF_API_KEY and restart, or use start_login and then retry. It never says when to choose this over connect_cloudflare/connect_dns_provider/create_dns_credential, so the routing guidance is incomplete.

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

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

Adds substantial behavior beyond the annotations: public endpoint, deliberately uniform response to avoid a user-enumeration oracle, email channel sends nothing (email_sent=false / send_required=true), SMS returns empty deep_link that render_auth_link rejects, and JWT + refresh cookies are set on completion. It also warns that most clients fold tool results away, which is operational context no annotation could 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?

Purpose is front-loaded and the workflow is laid out as a scannable numbered sequence with reserved-capital emphasis on critical facts. It is on the long side, and a few asides (e.g. "The other channels dispatch nothing either way") could be tightened without losing meaning.

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

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

For a multi-step, channel-varying, side-effect-bearing bootstrap call, nothing an agent needs is missing: return payload per channel, verification semantics, post-verification state, and the requirement to surface output in the agent's own reply text. Output schema exists, yet the description still adds the interpretation an agent needs.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining channel-dependent requirements — email address for the email channel, E.164 phone for SMS DID routing, and which channels return deep_link/qr versus sms_message.

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 an account-bootstrap session for agent-driven onboarding") and immediately scopes it as a public, no-API-key endpoint. It also names its workflow companions (send_account_email, render_auth_link, wait_for_account_creation, get_current_user), which separates it from the many sibling session/login tools.

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 agent workflow, states when to call the alternative (get_current_user after verification to distinguish new vs. returning users), and gives negative guidance (don't hand qr_text to a link renderer, don't invent a destination number for SMS, don't wait before showing the user the challenge).

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 annotations, the description discloses that the secret is returned only in this response, must be stored securely, and will be visible in AI conversation context. It also explains the 2FA elevation flow and the behavioral consequence of profile_id binding, which is substantial. It does not elaborate on rate limits or what the returned object contains, but the output schema covers return shape.

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

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

The description is front-loaded with purpose and the critical one-time secret warning, followed by ordered 2FA steps and access requirements. Despite its length, every section is necessary for safely invoking this privileged creation tool, and there is no redundant 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?

Given the complexity of 2FA, account access, one-time secret handling, and optional sub-account binding, the description covers the practical invocation path well. Return-value details are appropriately left to the output schema, though additional guidance on choosing scopes could improve completeness.

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 scopes, profile_id, and environment. The description adds useful meaning for profile_id by explaining sub-account branding, but otherwise does not deepen parameter semantics beyond the schema 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?

The description opens with a specific verb and resource: 'Create a new API key.' It also clarifies that the secret is returned only once and that profile_id can bind the key, which distinguishes the operation from listing, revoking, or regenerating existing keys without naming those siblings explicitly.

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

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

It gives clear usage context and prerequisites: the operation requires 2FA, needs a Proof account, and should be called only after the 2FA flow is verified. The 403 recovery path is explicit, though it does not directly compare this tool with alternatives such as regenerate_api_key or list_api_keys.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — the created object is inert until the end user approves it, and creation requires a Proof account with PROOF_API_KEY configured plus a server restart. It does not cover whether repeated calls create duplicates or how long the pending state lasts, which is why 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, front-loaded paragraphs: what the tool creates and the approval semantics first, then the access prerequisite. Every sentence earns its place, though the ACCESS preamble is operational noise for an already-authenticated agent.

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 9 parameters, an output schema, and thin annotations, the definition supplies what the structured fields cannot: the approval workflow and the account prerequisite. It is nearly complete for the calling decision; the remaining gap is the relationship to sibling authorization/confirmation tools.

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 enum values, patterns, and the deprecation of business_name, so the schema already carries parameter meaning. The description adds nothing about individual fields (for example, phone versus bsuid per channel), 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 uses a specific verb and resource ("Create a new authorization request") and explains the domain concept: an authorization grants permission to send confirmations to a user over a channel, and the user must approve it. That distinguishes it from generic creation tools, but it never names the adjacent siblings it could be confused with (create_confirmation, request_hitl_authorization, create_verification_request), so the differentiation 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?

Usage is implied rather than stated: the agent learns an authorization is a prerequisite for sending confirmations, and the ACCESS note usefully excludes start_login as a way to unlock the tool. However, there is no explicit guidance on when to call create_authorization versus request_hitl_authorization or create_confirmation, nor on what to do if an authorization already exists.

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 by disclosing the auth prerequisite (PROOF_API_KEY, restart required, start_login does not unlock it) and the client-level behavior that users never see tool results, which changes how the agent must respond. It also explains what each returned artifact is and what it must not be used for.

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 a labeled 'Agent usage' block and an access note — good structure. Minor waste: the user-invisibility paragraph mentions 'SMS text and number' and inbox checks, which belong to other tools and do not apply here.

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?

An output schema exists, yet the description still usefully names the returned fields and their roles in the flow, plus the auth gate and the downstream poll step. Nothing an agent needs to invoke this correctly and continue the workflow is missing.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to carry; it correctly spends its words on the returned token and artifacts instead.

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 Telegram chat ID discovery token') and immediately names the three return artifacts (deep_link, qr_code, qr_text). It is clearly distinguishable from siblings poll_chat_id_discovery and wait_for_chat_id_discovery, which it explicitly hands off to.

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 'Agent usage' sequence: pass deep_link to render_auth_link, do not pass qr_text to a renderer, then poll poll_chat_id_discovery until chat_id appears, then use it in a Telegram-channel HITL config. It names the follow-up tools and the terminal-state condition ('until the chat_id appears').

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 goes further by disclosing the auth prerequisite, the fact that start_login will not satisfy it, and what happens to declared member channels (stored so members can be invited later). It does not cover duplicate-name behavior, idempotency, or what the create response contains, which the presence of an output schema partly excuses.

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

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

Three short paragraphs, front-loaded with the definition, then the agent workflow, then access constraints — an agent reading only the first sentence already knows what the tool does. The access paragraph's restart instruction is slightly operationally verbose but earns its place by preventing a failed call.

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 create tool with five parameters, full schema descriptions, annotations, and an output schema, the description supplies exactly what structured fields cannot: the domain model, the follow-on workflow, and the auth gate. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining that members may be seeded at creation as an alternative to add_circle_member and that their declared channels persist for later enrollment. It says nothing about profile_id or proof_me_enabled beyond what the schema already states.

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

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

Names a specific verb and resource ("Create a Circle") and defines the resource in domain terms: a named group of trusted contacts powering Proof-Me and Approvals-on-Circle. That framing distinguishes it cleanly from list_circles, get_circle, update_circle and delete_circle without opening any schema.

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

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

The "Agent usage" paragraph gives an explicit sequence: create, then add_circle_member or seed members here, then invite_circle_member to mint the enrollment link. It also states a hard exclusion — "start_login does NOT open this tool" — and the prerequisite (set PROOF_API_KEY and restart), which is more than most definitions offer.

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 supplied annotations (readOnlyHint=false, destructiveHint=false), the description discloses the substantive behavioral traits: an actual challenge is dispatched to a real person, it carries the scheduled-safety-check label, and specific failure modes and their codes are given (422 plan_upgrade_required for live keys on Pay as you go, 400 no_channel when the member lacks a verified Telegram channel). It also explains the test-key asymmetry, which materially changes what an agent should expect. Nothing contradicts 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?

Front-loaded with the action and the 'drill vs automated sweeps' framing, then grouped into error-behavior and access blocks. Dense but nearly every clause carries operational weight; the parenthetical '(the account owner practices confirming)' is the only mildly expendable phrase.

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 mutation with an output schema, the description covers purpose, plan gating, channel precondition, and credential setup (PROOF_API_KEY + restart, plus the explicit note that start_login does not unlock it). The main residual gap is what an agent should do after firing — e.g., whether results are observed via the output schema or polled elsewhere — and any rate-limit or idempotency expectations for repeated drills.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the member_id must identify an *enrolled* member, and that member needs a verified Telegram channel (under a test key) or the call fails with 400 no_channel. That constraint is not expressible in the schema's 24-hex-char pattern and directly informs parameter selection.

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

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

The description opens with a specific verb and resource — 'Fire an on-demand Proof-Me drill against one enrolled member' — and immediately characterizes it as 'a real cross-channel identity challenge carrying the scheduled-safety-check label.' It also positions the tool against automated siblings ('Complements the automated daily drill + monthly reinforcement sweeps'), so an agent can separate this on-demand drill from scheduled sweeps 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?

Clear context for when to reach for this tool: on-demand, single member, versus the automated daily/monthly sweeps. It further gates usage by plan ('On Pay as you go a live key is refused 422 plan_upgrade_required') and by channel availability. It stops short of naming a direct alternative sibling (e.g., create_verification_request or trigger_verification) for the case where this tool is unavailable, so it is slightly under-specified on exclusions.

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 read=false/destructive=false, so the description carries the rest and does it thoroughly: the request fans out to configured channels, the first response wins, encryption is mandatory, and specific 400 error codes (message_not_encrypted, message_key_mismatch, envelope_missing_approvers) are documented. It also discloses the access precondition (PROOF_API_KEY required, start_login will not help), which is non-obvious failure-mode information.

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

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

Front-loaded with the purpose sentence, then grouped into usage, then encryption rules — logical for a multi-step tool. It is long, and the plaintext-refusal error code is stated both in the description body and again in the message schema, so a small amount of text is duplicated rather than additive.

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 an output schema and three documented parameters, the definition covers everything an agent needs before calling: authorization prerequisite, envelope construction, failure signals, and the two routes for checking the outcome. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds substantial meaning beyond it: it explains the v1 vs v2 envelope choice by 'who must be able to decrypt', the enrolled-approver rule that makes v1 fail, the approver_ek map, and the SDK helpers encryptMessageV2/getApproverKeys with the AAD being hitlId. That is decision-relevant construction guidance not present in 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: 'Create a HITL confirmation request' and immediately explains the effect — an approval request is broadcast to the channels on the referenced HITL config, with 'First response wins' as the resolution rule. This clearly distinguishes it from siblings like get_confirmation, wait_for_confirmation, and create_verification_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?

Explicit 'Agent usage' block states the prerequisite (hitl_id must be authorized), the recovery path on 403 (call request_hitl_authorization then wait for channel approval), and names both follow-up alternatives — get_confirmation for polling and get_confirmation_approval_link when the config owner decides themselves — with the condition that selects each.

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 behavior beyond the annotations: each mint is billable, an over-long expires_in is rejected rather than silently truncated, and the response carries derived effective_status/is_valid so it matches list/get output. Auth setup is spelled out at the environment level. What is missing is any note on reversibility/idempotency — whether re-minting the same delegate creates a duplicate billable proof — which matters for a non-destructive-but-metered write.

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 definition, then constraints, then billing, then access — a sensible order with no filler. It is somewhat dense and the closing clause ('so the shape does not depend on which verb produced it') could be trimmed, but every sentence conveys operational 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 nested-object, three-parameter write with an output schema, the description covers the domain concept, the failure mode, the billing implication, and the credential prerequisite. Since an output schema exists, it is not obligated to explain return values, yet it tells the agent enough about the returned pair to plan downstream calls.

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, and the description earns an extra point by adding real semantics: expires_in is bounded by the control proof's remaining lifetime and fails rather than truncates, and control_proof must be the caller's own active domain proof, not any handle. It does not clarify server-side canonicalization effects on the delegate value beyond what the schema already says.

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 delegation (Proof of Delegation)') and then defines the exact semantics of the artifact: a control-proven domain authorizes a typed url/purl and receives a publishable signed token. It also scopes what the attestation does NOT claim ('nothing more; it says nothing about the artifact or the business behind it'), which separates it cleanly from siblings like create_authorization, verify_delegation, and get_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?

Gives concrete preconditions and an explicit exclusion: needs a Proof account, PROOF_API_KEY must be set and the server restarted, and 'start_login does NOT open this tool' — a genuinely useful anti-pattern warning given start_login exists as a sibling. It stops short of naming the alternative verb to call when you only want to read or verify an existing delegation.

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

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

The description adds real behavioral context beyond the annotations, most notably that credentials become visible in the AI conversation context — a non-obvious and important side effect for a secret-storing tool. It also states the auth prerequisite and restart requirement. It does not explain storage lifetime, encryption, or how stored credentials relate to list_dns_credentials/delete_dns_credential cleanup, which keeps it below 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 one sentence, followed by a security warning and an access block, with no filler. The ACCESS section is slightly verbose but earns its space by unlocking invocation for an unauthenticated agent.

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 an output schema exists and both parameters are fully documented in the schema, the remaining burden on the description is behavior and access, both of which are covered — including the credential-exposure caveat and the login path. An agent has enough to call it correctly, with only sibling differentiation 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 both provider (including example identifiers) and the provider-specific credentials object documented in the schema itself. The description adds no syntax or per-provider credential key guidance, so the baseline 3 applies — the schema does the heavy lifting.

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

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

The first sentence gives a specific verb and resource: store DNS provider credentials, tied to the purpose of automated domain verification. It is clear what the tool does, but it never distinguishes itself from close siblings such as connect_dns_provider, connect_godaddy, or verify_domain_with_credentials, so an agent cannot route between them 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?

Usage is only implied: the agent infers it should call this to persist credentials before automated verification. The ACCESS paragraph is genuinely useful setup guidance (PROOF_API_KEY or start_login), but it explains authentication, not when to pick this tool over the sibling connectors that also register DNS providers.

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 the non-obvious access gate (PROOF_API_KEY must be set and the server restarted) and the lifecycle state that a new config is unusable until authorized. That is real behavioral context beyond structured fields. It does not address naming collisions or what happens on duplicate creation, which keeps it from a 5.

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

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

Front-loaded with the purpose, then two clearly labeled blocks for agent usage and access gating. Dense but every sentence carries actionable content; the only minor cost is that the ACCESS block is stated in three short fragments rather than one.

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 annotations and an output schema present, the description covers the remaining gaps an agent needs: prerequisite access, mandatory follow-up call, and channel-specific discovery. It leaves unstated whether channels and circle_id are mutually exclusive and what happens when neither is supplied, which matters because only 'name' is in the schema's required list.

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 meaning the schema cannot: it tells the agent where a Telegram chat_id value comes from (create_chat_id_discovery) and frames timeout_seconds as a default rather than a per-request override. The either/or relationship between channels and circle_id is only asserted in the schema text, not reinforced 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 ('Create a HITL config') and immediately scopes what the resource governs: which messaging channels receive approval requests and the default timeout. This separates it cleanly from request_hitl_authorization, create_confirmation, and update_hitl, which are named in the usage section.

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

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

Gives explicit sequencing rules with named siblings: request_hitl_authorization must be called after creation and before create_confirmation will work, and Telegram channels require create_chat_id_discovery first. It also rules out a plausible-but-wrong path by stating start_login does NOT unlock this tool.

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 annotations: discloses that it is asynchronous with a defined terminal-state set (confirmed, denied, cancelled, failed, expired, revoked), that the approval happens on a channel different from the suspicious one, and that authentication requires PROOF_API_KEY plus a server restart. The explicit note that start_login does NOT unlock this tool is unusually valuable context for an agent avoiding a failed call loop.

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 tight blocks — what it does, the approval mechanic, the agent polling loop, and the access prerequisite — with the purpose front-loaded and no filler sentences. 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?

An output schema exists, so return values need not be explained, and the description still covers prerequisites, async behavior, and terminal states. It omits polling cadence/backoff and failure recovery, which an agent managing a multi-second wait would want.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the suspicious_channel parameter is relational — it drives which channel the account holder must be reached on, namely one different from it. It still does not explain circle_id/member_id relationships beyond what the schema already states.

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

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

Names a specific verb and resource: create a Proof-Me cross-channel identity challenge (CONFIRM) for an enrolled Circle member, and the second sentence explains the cross-channel mechanic that makes this distinct from a plain confirmation. It stops short of naming a concrete sibling (create_confirmation, create_multi_channel_verification) as the alternative, so differentiation is implied rather than explicit.

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 operational workflow (poll get_identity_challenge with the returned ID until it leaves pending) and states the precondition that the member must be enrolled in a Circle. It does not say when to prefer this over the other confirmation/verification tools or when it is inappropriate.

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 goes far beyond by explaining first-wins cancellation of losing siblings, that exactly one proof is billed at the winning channel's completion and nothing at creation, and the critical client behavior that users never see tool output. That last point changes how the agent must format its reply.

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 segmented into purpose, agent usage, UX warning, and access, with the core semantics front-loaded. Nearly every sentence carries operational weight, though the access/auth paragraph could be tightened slightly.

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

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

For a 7-parameter creation tool with nested objects and an output schema, the definition covers the full lifecycle: creation, response shape, follow-up polling, proof retrieval, billing, and auth setup. Nothing an agent needs in order to call and act on 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 the baseline is 3, but the description earns more: it explains that the channels array is raced in parallel with first-completion winning, that the returned channels blocks each carry a deep_link or sms_message, and that qr_text is the same link pre-rendered rather than an alternate address — a distinction the schema cannot convey.

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

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

Opens with a specific verb and resource ("Create a multi-channel phone verification") and immediately defines the mechanic: one phone number challenged over several channels with OR / first-wins semantics. It is unambiguously distinct from the sibling polling tool get_multi_channel_verification_status, which it names.

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 what to do after creation (pass deep_link to render_auth_link, poll get_multi_channel_verification_status with group_id) and what not to rely on (start_login does NOT open this tool). Prerequisites — PROOF_API_KEY, server restart — are stated with a concrete remedy.

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 write/mutating nature is known; the description's real contribution is the authentication prerequisite and restart requirement, which the annotations do not convey. It does not address why a create carries destructiveHint=true, whether the operation is reversible via delete_profile, or whether profile count or primary-profile conflicts are constrained.

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 paragraphs: purpose first, access constraint second, with no filler or repetition. The all-caps ACCESS block is slightly shouty but is front-loaded enough to be 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?

An output schema exists, annotations cover the safety profile, and all 10 parameters are documented, so the description only needed to add purpose and access context, which it does. The remaining gap is behavioral detail around primary-profile selection and reversibility for a 10-parameter mutation.

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 the nested theme object, so the schema already carries field-level meaning. The description's field list largely restates those categories and adds no syntax, defaults, or interaction rules (e.g. how is_primary behaves when a primary already exists, or the avatar size limit already noted in 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?

The description opens with a specific verb+resource ("Create a new profile") and enumerates the optional field families it accepts (display name, bio, avatar, business info, email branding, theme), so an agent immediately knows what the call produces. It does not explicitly differentiate from nearby siblings such as update_profile or create_account, which keeps it from 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?

It gives an explicit precondition (needs a Proof account, set PROOF_API_KEY and restart) and a negative routing statement ("start_login does NOT open this tool"), which prevents a plausible wrong-path attempt. It stops short of saying when to create versus update an existing profile, so the use-case selection guidance is incomplete.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the response shape, the fact that the user never sees tool results, the SMS flow's quirks (no reply SMS, delayed spoof check that can revoke a proof about a minute after completion), and the authentication prerequisite (PROOF_API_KEY plus restart, and that start_login does not open this tool). That is substantial behavior an agent could not get from the 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 and return values are front-loaded and every paragraph carries operational content, but the draft is long and slightly redundant — the 'user does not see tool results' point is made once about render_auth_link's output and again as a directive before waiting/polling. The SMS paragraph in particular is dense enough that a reader may need a second pass.

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, stateful creation tool with nested parameters, the definition covers creation, rendering, polling, revocation risk, and credential setup. An output schema exists, so the description's return-value summary is a convenience rather than a necessity, and nothing an agent needs in order to call this 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 75% and the description adds real meaning about channel behavior: telegram/whatsapp are read from the account by a bot while sms requires the person to text a short code from the number being proven, and no phone number is submitted. It does not elaborate on profile_id, client_metadata, or the context.action enum, leaving those to 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?

The opening sentence gives a specific verb and resource ('Create a new phone verification session') and immediately names the returned artifacts (deep_link, qr_code, qr_text) plus the hosted-flow-with-callbacks model. It does not explicitly contrast itself with adjacent siblings such as create_verification, start_2fa, or create_multi_channel_verification, so an agent must infer the boundary from the word 'session'.

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 ordered workflow: create, hand deep_link to render_auth_link, then poll with wait_for_session until verified/failed/expired, and check validate_proof before relying on an SMS proof. It also states a prohibition ('Never hand qr_text to a link renderer') and the exact condition under which qr_text should be printed verbatim, which is the kind of when/when-not guidance that prevents misuse.

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=false and destructiveHint=false, it discloses account and authentication requirements, the server-restart requirement, session-based access, and the need to call the tool again after signing in. It adds less about the resulting request's lifecycle or what happens after creation.

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

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

The purpose is front-loaded, and the separate ACCESS paragraph makes setup and recovery steps easy to scan. The asset sentence is somewhat redundant with the richly documented schema, but the description remains compact and focused.

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?

Together with the complete input schema, output schema, and safety annotations, the description provides enough purpose and access context for successful invocation. Its main remaining gap is selection context among near-duplicate creation siblings, particularly create_verification_request.

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 the assets structure, allowed types, defaults, and constraints in detail. The minimal email-asset example is helpful but substantially repeats the schema's own description and example rather than adding new semantics.

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

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

The opening sentence gives a specific verb, resource, and audience: creating a verification request that asks another user to share verified assets. It does not distinguish this tool from the especially close sibling create_verification_request or other creation tools.

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 supplies concrete prerequisites and two actionable authentication paths: configure PROOF_API_KEY and restart, or use start_login and retry. It clearly establishes the sharing-request use case, but gives no guidance on when to prefer this tool over create_verification_request or related alternatives.

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