@proof-holdings/mcp-server

Official

by ProofHoldings

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Hybrid

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.0
Disambiguation2/5
Many tools have unclear boundaries: there is a dense cluster of domain verification tools (verify_domain, trigger_verification, check_domain_verification, verify_domain_with_credentials, start_domain_verification, start_user_domain_verification, check_user_domain_verification) that all trigger or check the same underlying flow, and start_2fa vs start_2fa_for_action, update_profile vs update_my_profile, and list_verification_requests vs list_my_requests are easy to confuse. An agent would frequently need detailed descriptions to pick the right tool.
Naming Consistency4/5
Tool names overwhelmingly follow a consistent verb_noun snake_case pattern (list_*, get_*, create_*, update_*, delete_*, revoke_*, wait_for_*). Minor deviations exist, such as test_verify, search, and the overlapping start_/create_ verb choices, but the overall convention is predictable and readable.
Tool Count1/5
176 tools is an extreme count for an MCP server, far beyond the well-scoped 3-15 range. While the server covers many domains (verifications, profiles, domains, HITL, circles, delegations), the surface is enormous and bloated with near-duplicate polling and verification helpers, making it very heavy for an agent to navigate.
Completeness4/5
The tool surface is exceptionally broad, with full CRUD/lifecycle coverage for most resources: verifications, profiles, domains, API keys, templates, HITL configs, circles, authorizations, and delegations. Minor gaps exist — no webhook endpoint management, no single-verification cancel, no confirmation deletion — but agents can generally work around these.
Average 4.1/5 across 176 of 176 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It mentions checking DNS records, but does not state side effects, async behavior, failure modes, whether ownership gets persisted, or what happens after verification. The access note is operational context, not behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core description is short and front-loaded, with the access note placed after. The wording has slight redundancy ('Trigger domain verification' and 'Checks DNS records...'), but overall it is compact and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large sibling set with many similar domain-verification tools, the description lacks crucial routing information. It does not explain how verify_domain differs from start_domain_verification, check_domain_verification, or verify_domain_with_credentials, and there is no output schema to clarify the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single param 'id' is already documented as 'Domain ID to verify'. The description adds no extra meaning to the parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Trigger domain verification') and resource ('domain'), and explains the goal ('confirm domain ownership'). However, it does not distinguish itself from closely named siblings like start_domain_verification, check_domain_verification, or verify_domain_with_credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides authentication prerequisites but no guidance on when to use this tool versus the many domain-related alternatives. It neither names competing tools nor gives selection criteria, so an agent cannot confidently choose it over similar siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does mention the authentication requirement, which is useful, but it does not disclose that adding a domain is a state-changing write operation, whether it triggers any verification workflow, what side effects occur, or what the tool returns. For a mutation tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and the ACCESS block provides necessary authentication context in a separate labeled paragraph. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers parameters and the description covers access, but the tool has no output schema and is part of a multi-step verification domain flow. The description does not explain what happens after adding the domain, what response to expect, or what the next recommended step is. This leaves an agent without enough context for a complete invocation or follow-up.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters. The description's phrase 'email sending intent' adds a bit of interpretive context for for_email_sending and 'verification method' maps directly to verification_method, but it does not add meaningful detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Add a new domain to verify ownership.' It also mentions the optional email-sending intent and verification method. It does not explicitly differentiate itself from sibling tools like verify_domain or start_domain_verification, but 'add a new domain' is specific enough to establish its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear access prerequisites: a Proof account, PROOF_API_KEY, or signing in via start_login. However, it does not explain when to use this tool versus alternatives, such as after adding a domain then using verify_domain, or avoiding add_domain if the domain already exists. Usage is implied by 'add a new domain' but not explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose an important permission limit ('Only the creator can cancel') and the auth path, which adds context beyond the schema. However, it does not describe side effects, whether cancellation is reversible, or what happens to the request afterward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. The access note is somewhat long but provides necessary auth context for an agent. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter cancellation tool, the description covers the main action, creator restriction, and access requirements. But it lacks any guidance on distinguishing this from the closely related cancel_verification_request, and it does not mention expected return behavior or post-cancellation state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full coverage for the single parameter: 'Verification request ID to cancel' with 100% coverage. The description adds no additional meaning about the id format, required state, or how to obtain it, so it does not improve on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and object: 'Cancel a pending verification request.' It is specific enough about the operation. However, it does not distinguish this tool from the similarly named sibling cancel_verification_request, so some ambiguity remains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives access prerequisites ('needs a Proof account', API key setup or login) and a constraint ('Only the creator can cancel'), but it provides no guidance on when to use this tool versus alternatives like cancel_verification_request, nor any exclusions based on request state or ownership verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing side effects. It does state that this tool sends an email and that authentication is required. However, it does not mention idempotency, duplicate-send behavior, or what happens if the verification request ID is invalid or unauthorized.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loads the core purpose before the access note. The access block is useful but includes environment-specific instructions like 'restart this server' that could be considered outside the essential tool description; overall, there is no wasted filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description covers the core operation and the necessary authentication precondition. It does not describe the email content or post-send behavior, but those are not required to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, id, is already described in the schema as 'Verification request ID' with 100% coverage, so the description adds little semantic value. The phrase 'subject of a verification request' contextualizes the ID but provides no additional format or usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Send an email notification') and a specific resource ('subject of a verification request'), so an agent can infer the operation. It does not explicitly contrast with sibling tools like resend_verification or send_account_email, but the resource and action are specific enough to avoid major ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides access prerequisites (Proof account, API key, or start_login) but does not say when this tool should be chosen over alternatives. No sibling comparison, exclusions, or conditions are given, so the agent must infer usage solely from the name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It adds a useful access prerequisite, but does not disclose side effects, idempotency, failure behavior, or whether confirming the code fully verifies the domain. For a mutating action, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the first line states the action, and the second paragraph covers access requirements. There is no filler, redundancy, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with fully documented schema, the description is adequate and includes an important access note. However, with no output schema and no annotations, it does not clarify what the confirmation returns, whether it is the final step in the domain email verification flow, or what happens on success or failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents both parameters: id as 'Domain ID' and code as 'Verification code from the email'. With 100% schema coverage, the description adds no additional parameter semantics, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action: confirming domain email verification by submitting the emailed code. The verb 'confirm' plus resource 'domain email verification' and method 'submitting the code' make the tool's purpose clear, though it does not explicitly contrast with sibling tools like start_domain_email_verification or check_domain_email_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear access precondition (Proof account, API key, or start_login session) and implies the tool is used after a code is sent to a corporate email. However, it does not explicitly state when to use this tool versus related alternatives, leaving the usage timing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It adds important operational context: authentication via API key is required and the login flow does not authorize this tool. It does not describe pagination defaults, response shape, or rate-limit behavior, but the read-only nature of 'List' is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: the first sentence states the purpose, and the ACCESS block delivers only essential operational instructions. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an optional-parameter list tool, the description covers the key auth prerequisite and the schema covers parameters, but it lacks output/return hints and does not route between competing asset-listing siblings. The partial list of asset types (missing social/wallet) also leaves a small completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented with enums for type and status. The description adds no parameter-specific meaning, and its parenthetical asset examples omit the social and wallet types present in the type enum, though the schema compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('List all verified assets') and defines the resource as verified identities with examples (phones, emails, domains). It is specific enough to understand what the tool does, though it doesn't explicitly contrast with siblings like get_profile_assets or list_verified_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful access prerequisites (Proof account, PROOF_API_KEY, restart server) and warns that start_login doesn't open this tool, but it gives no guidance on when to choose this over alternative listing tools such as get_profile_assets, list_emails, list_phones, or list_domains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It discloses the expected return content, the API-key requirement, and a warning about start_login. It does not describe error or not-found behavior, but for a simple read-only getter this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and return fields are front-loaded in the first sentence. The access note is a separate paragraph and slightly unusual, but it is relevant context and not overly verbose. The structure is functional and every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool this is mostly complete, but with no output schema and a very large sibling set, it should at least mention that wait_for_session is the polling alternative or clarify when a session has an ID ready to retrieve. The access prerequisite is helpful but does not fully cover the selection context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter fully with 'Session ID' at 100% coverage. The description only repeats 'by ID' and adds no additional semantics about format, required length, or lookup behavior, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('session'), the operation ('Get by ID'), and the key return fields (status, verification details, proof token if verified). It is specific enough to be understood, though it does not differentiate get_session from the closely related wait_for_session sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus wait_for_session, list_auth_sessions, or create_session. The access note about PROOF_API_KEY and restart is a prerequisite, not usage guidance, and the claim that 'start_login does NOT open this tool' is confusing rather than a clear exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It does disclose the async nature ('once the user interacts with the bot') and the API key requirement. It does not explain what happens before the user interacts, whether repeated polling is expected, or error/timeout behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded in the first sentence, and the access note is compact. The 'start_login does NOT open this tool' note is somewhat tangential and could be clearer, but there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter polling tool, the description covers the basic call flow and return values. However, it omits polling semantics, pre-interaction behavior, and a pointer to the related wait_for_chat_id_discovery tool, leaving minor but real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the token parameter already has a clear schema description: 'Discovery token from create_chat_id_discovery'. The tool description adds little beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Poll a chat ID discovery token' and explains what is returned (Telegram chat ID, user ID, username). It does not explicitly contrast itself with the sibling wait_for_chat_id_discovery, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The access note gives helpful context: a Proof account and PROOF_API_KEY are required, and the tool should be called again after setup. However, it does not explain when to use this poll tool versus wait_for_chat_id_discovery or other alternatives, leaving usage mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the Proof account requirement and the session-flow requirement ('sign in with start_login — a session opens this tool — then call this tool again'). It does not mention side effects, reversibility, or what configuration changes are made.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded in two sentences, and the ACCESS instructions are separated into their own paragraph. There is slight redundancy between 'Set up email sending' and 'Configures the domain for sending verification emails', but the overall structure is compact and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition covers the authentication prerequisite and basic input semantics, which is enough to attempt a call with id and from_email. However, it lacks return behavior, success signaling, and explicit relationship to related domain email verification tools, and there is no output schema to fill those gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents 'id' and 'from_email'. The description's 'custom address' phrase adds no technical detail beyond the schema, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action: 'Set up email sending for a verified domain' and clarifies it configures sending verification emails from a custom address. This distinguishes it from verification-oriented tools like verify_domain and start_domain_email_verification, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used for an already-verified domain and to set a custom from-address, and it provides auth prerequisites. However, it gives no explicit when-to-use vs. alternatives guidance and does not mention which sibling tools should be used instead in other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose an important operational requirement (Proof account, PROOF_API_KEY, server restart) and corrects a possible misconception about start_login. However, it does not explain side effects, whether the check is asynchronous, whether it can be re-triggered, or what happens on failure—so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one clear purpose sentence followed by a practical access note. Both sentences earn their place, and the most important information is front-loaded. The access note is slightly fragmented but still concise and actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description is mostly adequate and includes a valuable setup gotcha. Still, it omits the tool's relationship to the broader verification workflow and what the agent should expect after triggering the check, leaving some contextual ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter 'id' as 'Verification ID', so schema coverage is 100%. The description adds no parameter-level detail, which is acceptable because the schema already carries the meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Trigger'), a clear resource ('DNS/HTTP verification check'), and a precondition ('pending domain verification'), which makes the tool's purpose understandable. However, it does not explicitly differentiate itself from closely related siblings like check_domain_verification or verify_domain, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a pending domain verification' implies when the tool should be used, and the access note gives a concrete prerequisite. But it never explicitly says when to prefer trigger_verification over sibling tools such as verify_domain, start_domain_verification, or check_domain_verification. The mention that 'start_login does NOT open this tool' is a useful exclusion but not a full usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses access requirements, environment setup, and a scope limitation, which is useful. It does not disclose whether branding updates are partial or full replacements, what response to expect, or how errors/manifest missing keys are surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with the core action in the first sentence and the access note separated clearly. It is efficient, though the access instructions could arguably live in a dedicated auth note rather than the main description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The critical access prerequisite and current scope are covered, which is valuable for someone attempting to call the tool. Still, for a write operation with no output schema and no annotations, the description should also clarify update semantics, return values, and common failure modes to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 branding object and all its properties. The description only adds the phrase 'branding configuration', which does not materially enhance the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates account settings and narrows the current scope to branding configuration. This gives an agent a specific verb, resource, and functional area. However, it does not explicitly distinguish itself from related sibling tools like update_my_profile or get_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable usage context: it requires a Proof account, PROOF_API_KEY setup, and a server restart, and it explicitly warns that start_login does NOT open this tool. It does not, however, explain when to choose update_settings over other settings/profile-related tools or mention any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose a rate limit (10 attempts per minute) and authentication requirements. Yet it does not describe what happens after submission (success/failure response, whether the code is consumed, or if the session is invalidated), so behavioral coverage is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: the main action appears first, followed by rate limit and access instructions. The access sentence is somewhat dense with em dashes, but every clause conveys necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, rate limit, and access prerequisites, but with no output schema, it leaves return values unspecified. It also does not reference the surrounding flow (e.g., obtaining session_id via start_2fa or wait_for_2fa), so an agent gets a functional but incomplete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 'code' and 'session_id'. The description adds no extra meaning or context about obtaining these values, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('Submit') and resource ('verification code' to complete a 2FA challenge). It is unambiguous about the operation, but does not explicitly distinguish from sibling tools like submit_verification_code or verify_2fa_magic_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical access context: requires a Proof account, PROOF_API_KEY, or signing in with start_login to open a session. However, it does not state when to prefer this tool over alternatives or when not to use it, leaving selection among many 2FA/verification siblings to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds an access requirement and a restart/session flow, which is useful operational behavior. However, it does not disclose side effects such as whether the previous primary phone is automatically demoted or whether the phone must be verified before this operation succeeds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action is front-loaded in a concise first sentence. The second sentence provides necessary access/authentication steps, though it is slightly verbose with the restart and sign-in alternatives. Overall, there is no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation with no output schema, the description covers the operation, the required parameter source, and authentication requirements. It does not mention how to obtain a phone record ID or what the response is, but those are less critical given the clear schema and sibling tool list_phones.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter, 'id', with 'Phone record ID to set as primary', covering 100% of parameters. The description adds no additional meaning beyond this, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Set'), a specific resource ('a phone number'), and the target state ('primary phone for the account'). This clearly distinguishes it from sibling tools like set_primary_email and set_primary_profile by naming the phone resource explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as list_phones or set_primary_email. The only contextual note is the ACCESS prerequisite about needing a Proof account or starting a login session, which is operational setup rather than a usage-selection guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the action is a credential access check and includes an ACCESS note about authentication prerequisites, which is helpful. However, it does not disclose return values, error behavior, rate limits, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and efficient: two sentences define the tool and its use case, followed by a short ACCESS block. Every sentence serves a purpose, and the structure is front-loaded with the core function before authentication details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter check tool with no output schema, the description covers the essential context: what it does, when to use it, and how to authenticate. The lack of return-value/error details is a minor gap given the tool's simplicity and the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'id', is fully described in the schema as 'Domain ID to check credentials for,' giving 100% schema coverage. The description adds no additional semantic detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Check if stored DNS credentials have access to a domain') and identifies the resource (domain credentials). It distinguishes itself from actual verification tools like verify_domain_with_credentials by framing this as a preflight access check, though it does not explicitly name a sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use before triggering verification to confirm the credentials work' provides an explicit, actionable usage context. It does not list when-not-to-use or alternative tools, but the guidance is specific enough for an agent to determine appropriate invocation timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It correctly implies a read-only status check and adds useful context about required authentication. However, it does not explain what happens if the domain does not exist, whether the check triggers any background work, or what specific DNS record states are surfaced. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the tool's core purpose, followed by a necessary access note. Both sentences earn their place, with no extraneous detail or repetition of schema information. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one simple parameter and no output schema, the description covers the essential purpose and the access precondition. It mentions DNS record configuration progress, giving an agent a sense of what the status includes. It could be more complete by describing likely status values or return structure, but the overall context is sufficient for a straightforward status check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'id' parameter as 'Domain ID', and schema description coverage is 100%. The tool description adds no further meaning to the parameter, such as expected format or how to obtain the domain ID. Baseline 3 is appropriate because the schema handles the parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Check the email sending setup status for a domain, including DNS record configuration progress.' This clearly distinguishes the tool from related sibling tools like check_domain_verification, which focus on verification rather than email sending setup. The phrasing is concrete and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides access prerequisites (needs a Proof account, API key or start_login) but gives no guidance on when to use this tool versus alternatives such as check_domain_verification or setup_domain_email. There is no explicit when-to-use or when-not-to-use context, leaving the agent to infer the tool's role from its name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the authentication/session requirement and the 'completed' state precondition. However, it does not describe what 'claiming' does to the assets or the request, whether the operation is destructive or idempotent, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the primary purpose, followed by a compact access note. The second sentence is slightly run-on, but it contains no filler and each clause carries useful operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter action, the description is largely complete: it states the purpose, the required state of the request, and the auth steps. Minor gaps remain around the return value and how the request ID is obtained, but these do not block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter 'id' as a 'Verification request ID', with 100% schema description coverage. The description adds the context that the request must be completed, but no additional parameter syntax, format, or usage detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Claim'), a clear resource ('shared assets'), and a condition ('from a completed verification request'). It is not a tautology and conveys the tool's core function, though it does not explicitly differentiate from siblings like get_request_proofs or list_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: the request must be completed, and it explains the access prerequisite (Proof account, API key or start_login session). It does not explicitly mention alternatives or when-not-to-use cases, but the stated precondition is helpful for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the only place to learn that the tool is gated behind a Proof account or session, and it explains how to satisfy that gate. It also clearly frames the operation as creating a request rather than reading data. It does not disclose return shape or lifecycle behavior, but the auth disclosure is a substantial behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two purposeful sentences: one for the core purpose and one for the access requirement. It is front-loaded with the main action and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a state-changing creation tool with 10 parameters, no output schema, and no annotations, yet the description does not say what the call returns, how the other user is selected or notified, or how the request relates to sibling request-lifecycle tools. The access note is useful, but the overall context is incomplete for an agent deciding whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 10 parameters already have descriptions in the schema, so the description adds little parameter-level value. It reuses the notion of 'verified assets' from the assets parameter, but does not explain defaults, formats, or interactions beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a concrete action and outcome: create a new verification request that asks another user to share verified assets. It is clear, but it does not distinguish this tool from the sibling create_verification_request, whose name matches the described resource exactly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The ACCESS note gives a concrete prerequisite and remediation path (set PROOF_API_KEY, restart, or start_login and retry), which is helpful for invoking the tool. It never says when to choose this tool over create_verification_request or other request-creation siblings, so selection guidance is mostly inferred from the name and first sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the authentication requirement and implies a read-only operation by saying 'Returns...'. It does not mention error behavior, rate limits, or side effects, but for a simple getter the access constraint is the most important behavioral trait and it is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose in the first sentence, followed by a clearly labeled access note. The access instructions are useful and not redundant, though they could be slightly tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with no output schema, the description is reasonably complete. It states what is returned (account details, plan, settings) and explains the authentication prerequisites. It does not provide a full field-by-field output, but that is not required for a simple getter when no output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the baseline for this dimension is 4. There is no parameter information needed, and the description does not need to compensate for undocumented parameters since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current authenticated user's account details, plan, and settings for the API key owner. It uses a specific verb and resource. It doesn't explicitly differentiate from siblings like get_my_profile or get_settings, but the scope (account/plan/settings for the key owner) makes the purpose reasonably distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical access guidance: a Proof account is required, and the agent can either set PROOF_API_KEY or use start_login to establish a session before calling. However, it does not explain when to prefer this tool over alternatives such as get_self_api_key or get_settings, so the when-to-use-vs-alternatives dimension is only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add useful context: the operation returns paginated results and requires prior API key setup. However, it does not state that the operation is read-only, describe the response structure, or mention ordering/defaults, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by relevant access instructions. Every sentence adds information without redundancy, though the access block is slightly procedural and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers access prerequisites and mentions pagination, but with no output schema it does not describe the response format or default pagination behavior. Given the high number of sibling tools and the need to distinguish this operation, a bit more context about what a 'verification' is would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have descriptions in the schema, and the description simply refers to them as 'optional filters'. It does not add extra meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List verifications' with 'optional filters'. It is unambiguous about the core action, though it does not differentiate from sibling tools like list_verification_requests or list_verified_users, making the exact meaning of 'verifications' slightly dependent on context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access guidance: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted before retrying. It also warns that start_login does NOT open this tool, which is a clear when-not. It does not compare against alternative list tools, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses auth requirements and the fact that it returns rendered content, which is useful. However, it does not state whether any side effects occur or explicitly confirm that no message is sent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose and return value. The ACCESS note adds relevant operational context without excessive fluff, though 'start_login does NOT open this tool' is a slightly odd aside.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple render operation, the description is mostly adequate and includes critical access details. The main gap is that it does not explain how message_type selects a template or how variables map to template placeholders, which could leave an agent uncertain in a large sibling tool set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds no parameter-level meaning beyond what the schema already provides. The message_type field remains vague in both the schema and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Render a template with provided variables' and identifies the return value as 'fully rendered message content.' It is specific enough to understand the tool, though it does not explicitly distinguish itself from the sibling preview_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear access context: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted. It also warns that start_login does not open this tool. It lacks explicit comparison to alternatives like preview_template, but the prerequisites are unusually helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It explicitly discloses a rate limit of 3 requests per minute and an authentication prerequisite with a concrete recovery path, which are important behavioral details often omitted. It does not mention idempotency or failure behavior, but the core side effect is clear from the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence defines the action, followed immediately by the rate limit, then the access prerequisite. The access note is slightly long but each part earns its place by telling the agent how to authenticate and when to retry.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter resend tool, the description covers the action, rate limit, and authentication path. It does not explain what a successful response looks like or state that the domain email verification must already be in progress, which would be useful since no output schema is provided and the domain workflow has several stages.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters (id and email_prefix) with 100% coverage, including the enum for email_prefix. The description adds no parameter-level detail, so it correctly relies on the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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: 'Resend the domain verification email.' This clearly identifies the action and object, distinguishing it from sibling verification tools like verify_domain or start_domain_verification by emphasizing the resend action. It does not explicitly name an alternative, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear invocation context by stating the rate limit and the Proof account requirement, including how to obtain access via PROOF_API_KEY or start_login and then retry. However, it does not state when to prefer this tool over related alternatives such as start_domain_email_verification or resend_verification; usage timing is only implied by the 'resend' verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that this starts a verification session and requires authentication, which is useful, but it does not mention what the response contains, whether repeated calls create multiple sessions, or how the challenge is surfaced to the user. These are notable gaps for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the core purpose. The access paragraph is slightly awkwardly phrased but contains necessary operational details, so it earns its place despite minor verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description needs to give the agent enough to understand the full workflow. It explains the initial step and access requirements, but does not mention next steps like checking verification status or completing the challenge, which are relevant given the sibling tools and the multi-step nature of domain verification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description adds a small amount of context by mentioning DNS or HTTP challenges, but this merely mirrors the channel enum rather than adding new semantic meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start'), the resource ('domain verification session'), and the mechanism ('DNS or HTTP challenge'). However, it does not explicitly differentiate from the sibling tool start_domain_verification, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to invoke the tool: a Proof account is required, and the agent must either set PROOF_API_KEY or authenticate via start_login. It does not explicitly list alternatives or exclusions, but the access conditions are specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the 409 duplicate-channel conflict, server-side per-channel format validation, and the PROOF_API_KEY authentication requirement. It does not mention success response shape or behavior for invalid IDs, but the disclosed behaviors are the most operationally significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a one-sentence purpose, one sentence for the 409 edge case, one sentence clarifying identifier formats, and an actionable access note. The purpose is front-loaded and every sentence earns its place, though the access paragraph is slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the most important context: auth setup, duplicate detection, and identifier validation. Gaps include what a successful call returns and how this tool relates to list_circle_member_channels, but the heavily documented schema compensates for parameter-level completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even with no parameter info in the description. The description mostly restates the identifier format already in the schema, adding only the nuance that format is 'validated server-side,' which is marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Declare a channel for a Circle member.' The 409 error detail clarifies that this is a create/register operation, which distinguishes it from list/remove siblings such as list_circle_member_channels and remove_circle_member_channel. However, it does not explicitly name any sibling, so differentiation relies on the verb choice rather than direct contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The access note ('needs a Proof account', 'Set PROOF_API_KEY and restart this server') gives a concrete precondition, and 'start_login does NOT open this tool' provides a negative usage signal. But there is no explicit guidance on when to use this versus related tools, such as checking existing channels with list_circle_member_channels before adding or using remove_circle_member_channel to change a channel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral context. It discloses that a Proof account is required and explains how to authenticate, which is useful. However, it does not clarify whether the check is asynchronous, what side effects occur, whether repeated calls are safe, or what the response represents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded: the core instruction appears first, followed by a compact access note. Every sentence contributes useful information with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has one well-documented parameter, and the description covers when and how to call it. However, there is no output schema and no guidance about what to expect after triggering the check or which sibling tool to use next for status, leaving a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single `session_id` parameter with 100% coverage, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema, which is acceptable here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Trigger a check') on a specific resource ('domain verification challenge'), and adds sequencing context. However, it does not distinguish this from the sibling `check_domain_verification` tool, which could be confused with it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the caller when to use the tool: 'Call after placing DNS record or HTTP file.' It also provides access prerequisites and a fallback sign-in path. It does not discuss alternatives explicitly, but the timing and prerequisites are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the destructive outcome, the fallback behavior (reverting to default), and an access prerequisite (Proof account and PROOF_API_KEY). It does not mention irreversibility or return values, but the core side effect is clearly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The access/configuration note is relevant but somewhat operational; it does not waste words. It earns a solid score, though it could be slightly tighter by separating configuration instructions from tool semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with two required parameters and no output schema, the description covers the essential context: what is deleted, what happens afterward, and how to authenticate. It would be slightly more complete with an explicit distinction from delete_profile_template, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both channel and message_type already have descriptions. The tool description does not add extra parameter-level meaning beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Delete a custom template') and the consequence ('reverting to the default template for that channel and message type'). It is specific and informative, though it does not explicitly distinguish itself from the close sibling delete_profile_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action statement, but no alternatives are mentioned, and the closely related delete_profile_template is not addressed. The access guidance ('needs a Proof account', 'start_login does NOT open this tool') provides useful context but does not help an agent decide between this and other delete/update template tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full disclosure burden. It states that the operation returns counts only, contains no recipient identifiers, is scoped to the authenticated account, and that API-key callers can only read their own key. It also discloses the auth requirement and how to unlock access. This meaningfully exceeds a bare 'Get usage' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the first sentence covers purpose and output scope, then the ACCESS paragraph provides actionable setup instructions. The metric list is dense but relevant, and there is no filler or repetition. It is slightly long but each clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by enumerating the return categories: verification counts by type/channel/status, verification-request/confirmation/authorization totals, and attribution context. It also covers access setup and account scoping. It doesn't specify the exact response structure, but for a usage-read tool the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both `id` and `environment` have descriptive text in the schema. The description reinforces `id` ('for a given key id') but adds no extra meaning for `environment` or the default value. Baseline 3 is appropriate since the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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: 'Get per-API-key usage for a given key id'. It enumerates exactly what is returned (verification counts by type/channel/status, totals, attribution context), making the tool's purpose unmistakable. It doesn't explicitly contrast with sibling tools like get_usage or get_platform_summary, but the 'per-API-key' and 'given key id' phrasing inherently distinguishes it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear access prerequisites and scoping rules: 'Scoped to the authenticated account; an API-key caller may read only its own key', plus setup instructions using PROOF_API_KEY or start_login. However, it does not say when to prefer this tool over siblings like get_usage or get_platform_summary, and no explicit alternatives/exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the access requirement and that start_login is not a valid path, which is useful. However, it does not describe expected return structure, error behavior, or any safety/read-only characteristics beyond the verb 'Get.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose and content are front-loaded, followed by a separate ACCESS note. Every sentence adds value, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough to understand the tool's purpose and access prerequisites, but lacks important context such as how months and period interact, expected output shape, or behavior without parameters. Since there is no output schema and no annotations, more detail would help the agent invoke and interpret this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (months and period) already documented clearly. The tool description does not repeat or augment the parameter semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get usage metrics for the authenticated account' and enumerates what is included: 'verification counts, API calls, and quota usage.' This distinguishes it from generic usage tools, though it does not explicitly name sibling alternatives like get_api_key_usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit access context: it requires a Proof account, asks the user to set PROOF_API_KEY and restart the server, and warns that start_login does NOT open this tool. It gives clear when-to-use guidance regarding access, but does not name alternative tools for similar usage metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It discloses authentication requirements, the need to set PROOF_API_KEY and restart the server, and explicitly notes that start_login does not grant access to this tool. For a read-style operation, this is meaningful behavioral context, though it could additionally state side-effect-free behavior or not-found behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose, then adds a practical access note. The access block is slightly verbose but each sentence carries relevant setup or exclusion information. No unnecessary filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity—one required parameter, 100% schema coverage, no output schema—the description covers the essential context: what it returns, the authentication prerequisite, and a non-obvious access limitation. It is not exhaustive because it leaves sibling-tool relationships implicit, but it is sufficient for a simple by-ID lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single required parameter, id, with the description 'Verification request ID.' The tool description only repeats that it fetches by ID and does not add format, example, or relationship details, so it sticks to the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a verification request by ID,' and adds a concrete detail about the return value ('with all its asset verification statuses'). It is clear and actionable, though it does not explicitly distinguish itself from closely named siblings like get_verification or get_request_by_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use this when you have a verification request ID and need its asset verification statuses. It also communicates a clear precondition—needing a Proof account and PROOF_API_KEY—and warns that start_login does not enable this tool. However, it never names alternatives or explains when another verification-related tool should be chosen instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool returns paginated results, supports optional filters, and has an authentication prerequisite. It does not describe ordering, ownership scope, default page/limit behavior, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose comes first, followed by a useful ACCESS warning. Every sentence contributes necessary information, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough to attempt the call: access setup, filters, and pagination awareness. However, without an output schema and without distinguishing this tool from nearby list-related siblings, an agent may not be certain it selected the correct tool or know what the response shape will be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds only generic language about 'optional filters' and paginated results, without adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('verification requests'), and adds that results are paginated with optional filters. It is clear, but it does not differentiate from sibling tools like list_verifications, list_incoming_requests, or list_my_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The ACCESS block provides clear operational guidance: a Proof account and PROOF_API_KEY are required, a server restart is needed, and start_login does not open this tool. This is a clear when-not, but it does not mention alternative list tools or when to prefer one over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It usefully discloses the auth prerequisite and that start_login alone is insufficient, which is important operational context. However, it does not state whether updates are partial or full replacements, how unspecified fields behave, or what the response contains—significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear action sentence, a scope sentence, and a necessary access warning. No wasted words or redundant restatement of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutation tool with nested objects, no output schema, and no annotations, the description provides purpose and auth context but lacks operational completeness. It omits update semantics, response behavior, and guidance on how this tool relates to update_my_profile. It is adequate but leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter thoroughly. The description simply summarizes high-level categories like theme and custom links without adding parameter-level meaning. This meets the baseline but does not add extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Update a profile by ID.' It then enumerates the editable categories (display info, theme, custom links, verification display settings), which clarifies scope. It does not explicitly differentiate from update_my_profile, but the 'by ID' framing implies targeting a specific profile, which is reasonably distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access guidance: requires a Proof account, PROOF_API_KEY must be set, and the server restarted. It also explicitly warns that start_login does NOT open this tool, which is a useful exclusion. It stops short of naming update_my_profile as the alternative for updating one's own profile, so the when-to-use guidance is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses an authentication requirement and indicates the call changes public proof visibility, masking, and order, but it does not say whether the proofs array replaces all existing configurations, how omitted proofs are handled, or what side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact paragraphs with the core purpose front-loaded in the first sentence. The ACCESS note is concise and valuable, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and access guidance cover parameter structure and auth prerequisites, but since this is a mutating tool with no annotations and no output schema, the description should clarify whether the input is a full replacement or partial update. It also does not distinguish itself from update_profile_proofs, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for proofs, asset_id, is_visible, mask_level, and display_order. The description's first sentence restates visibility, masking, and display order without adding meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'Update' and resource 'which verified proofs are visible on the user's public profile', and lists visibility, masking, and display order as the modified aspects. This is clear and actionable, though it does not explicitly differentiate from the similarly named update_profile_proofs sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The ACCESS note provides concrete prerequisites and a clear two-step path: set PROOF_API_KEY or start_login, then call again. It gives clear context on when the tool is usable, but does not mention alternatives or exclusion conditions such as preferring update_profile_proofs for other profile proof changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly reveals that the tool is side-effecting ('Triggers a DNS/HTTP check') and that it returns the updated status, and it documents the auth requirement and setup step. It does not mention rate limits or error cases, but the core behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action and effect, and the second sentence covers access details. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, its side effect, its return value ('updated status'), and the required access setup. Since there is no output schema, a more detailed status vocabulary would be helpful, but nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single parameter id as 'Domain verification ID' (100% coverage). The description adds no additional parameter-level meaning, but none is strictly needed for such a simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation ('Check the status of a pending domain verification') and adds a differentiator by noting it 'Triggers a DNS/HTTP check and returns the updated status.' This distinguishes it from a pure read-only status tool, though it does not explicitly name a competing sibling to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete access prerequisites ('needs a Proof account. Set PROOF_API_KEY') and a clear exclusion ('start_login does NOT open this tool'). However, it does not explain when to choose this tool over related domain-verification siblings such as start_domain_verification, trigger_verification, or wait_for_verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It does warn that the API token will be visible in the AI conversation context and explains the session requirement, which is valuable. However, it does not disclose potential side effects, such as whether an existing connection is overwritten or whether the token is stored persistently, nor what success/failure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose, followed by a necessary security note and access instructions. All three sentences earn their place, though the access sentence is slightly dense and could be clearer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with full schema coverage, the description is mostly sufficient: it explains the purpose and the required access setup. However, it omits important operational context like whether the domain must already exist, whether this replaces an existing DNS connection, and what happens after a successful connection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both 'id' and 'api_token' with meaningful descriptions. The tool description adds no further parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Connect a Cloudflare API token to a domain') and its purpose ('automated DNS record management'). It clearly distinguishes this tool from siblings like connect_godaddy and connect_dns_provider by explicitly scoping it to Cloudflare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear access context: a Proof account is required, and it explains two ways to authenticate (PROOF_API_KEY or start_login). It does not explicitly compare against alternatives such as connect_godaddy or connect_dns_provider, but the Cloudflare-specific wording makes the intended use reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It does disclose a meaningful privacy/security concern: 'credentials will be visible in the AI conversation context.' It also explains the authentication flow. However, it does not state whether connecting replaces an existing DNS provider, whether the operation is reversible, or what happens after a successful connection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the primary purpose is front-loaded, followed by a concise security note and a short access instruction block. Every sentence earns its place. The access section is slightly wordy with the start_login flow, but it is still moderately compact and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, credential exposure risk, and authentication requirements, which are important. However, it does not explain how the agent knows the connection succeeded, whether an existing provider connection is overwritten, or how to discover supported provider identifiers. For an operation with no output schema and no annotations, this leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents id, provider, and credentials. The description's reference to 'provider-specific credentials' mostly restates the credentials parameter rather than adding new meaning. It does help contextualize why credentials exist, but it does not go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Connect a generic DNS provider to a domain using provider-specific credentials.' The word 'generic' clearly separates this tool from specialized siblings like connect_cloudflare and connect_godaddy, so an agent can immediately tell what it does and when it applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as the generic provider option, implying it should be used when a dedicated connector like connect_cloudflare or connect_godaddy is not applicable. It also provides explicit access prerequisites: needing a Proof account, setting PROOF_API_KEY, or using start_login to open a session before retrying. It does not explicitly name alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries a higher burden. It does add useful behavioral context: the tool requires an authenticated Proof account and an environment variable, and it cannot be reached through start_login. Yet it does not disclose side effects, response format, follow-up steps like waiting for the request, or any rate-limit/error behavior, leaving significant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears first, followed by a clearly separated access note. Every sentence adds value, and the formatting makes the prerequisite stand out without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 10 parameters, nested objects, no output schema, and many related sibling tools. The description covers access but omits essential operational context such as what the tool returns, how to poll or wait for the created request, and how it relates to request-status tools like get_verification_request or wait_for_request. For a tool of this complexity, the description is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameter meanings and defaults. The description adds only the high-level notion of multi-asset verification and access requirements, not any parameter-specific guidance. This meets the baseline but goes no further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a multi-asset verification request, lists the verifiable asset types, and emphasizes single-flow execution. This distinguishes it from sibling tools like create_verification or create_multi_channel_verification by highlighting the multi-asset nature and the request-based model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete access prerequisites: a Proof account, PROOF_API_KEY setup, and server restart. It also explicitly warns that start_login does NOT open this tool, preventing a common mistaken path. However, it does not explicitly compare with alternative request-creation or verification tools or state when to prefer this over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains the deletion action, the primary-profile edge case, and the Proof-account/API-key requirement, which is useful context. However, it does not disclose whether deletion is permanent, what cascading effects occur, or what response the caller should expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, while the second section adds necessary access and constraint details. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete tool with no output schema, the description covers the key preconditions: Proof account, API key setup, restart requirement, and the notable limitation about deleting a sole primary profile. It could mention response/return behavior, but the essential information for selecting and invoking the tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter, describing profile_id as 'Profile ID.' The description adds only 'by ID,' which does not meaningfully extend the schema's parameter semantics. A baseline of 3 is appropriate because the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a profile by ID.' The constraint about the primary profile further distinguishes it from profile mutation tools like update_profile or set_primary_profile. There is no ambiguity about the operation being performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an implied usage context and a clear operational prerequisite, but it does not explicitly state when to prefer this tool over alternatives or mention sibling tools such as update_profile. It does provide a negative routing signal with 'start_login does NOT open this tool,' which helps avoid incorrect invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does reveal the access requirement and implies a read-only status check, but it does not describe what statuses may be returned, whether polling is safe or rate-limited, or what the response will contain. This is a noticeable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in a single clear sentence. The access paragraph is somewhat verbose but relevant and does not obscure the main point. Overall it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description is adequate but incomplete. It explains what the tool checks and how to authenticate, but it does not document possible return statuses or how the session ID is obtained, which an agent would need to act on the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter, session_id, is described as 'Add-email session ID.' The description adds little beyond that, only reiterating that the operation is by session ID. This meets the baseline but provides no extra provenance or format guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Check the status of an in-progress email addition by session ID.' It clearly distinguishes this from siblings like start_add_email or get_add_phone_status by scoping it to an email addition and requiring a session ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is for an in-progress email addition, and it provides explicit access guidance for authenticated use, including setting PROOF_API_KEY or signing in via start_login. It does not explicitly name alternatives or exclusions, but the usage context is clear enough for a simple status-polling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool requires a Proof account and that start_login does not enable access, which is useful behavioral context. However, it does not explicitly state read-only behavior, error cases, or whether unverified assets are excluded beyond the word 'verified'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose is stated in the first sentence, and access requirements follow in a single additional paragraph. No redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter, the description is largely complete. It covers return fields and access constraints, even though no output schema exists. It omits not-found behavior or explicit read-only confirmation, but these are minor for a tool of this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the id parameter has a description ('Asset ID'). The description reinforces that the tool fetches by ID and adds the 'verified' qualifier, but it does not add format or validation details beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('single verified asset'), and the identifier ('by ID'). It also lists returned fields (type, value, status, verification timestamps), making it distinct from list_assets and revoke_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (fetching a single asset by ID) and provides access prerequisites (Proof account, PROOF_API_KEY, restart server), but it does not explicitly compare against list_assets or other asset-related siblings. The guidance is practical but not selection-oriented.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the auth prerequisite and the fact that start_login does not grant access to this tool. However, it does not mention return format, error behavior, or whether this is a read-only operation beyond the verb 'Get.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The access instructions are necessary and each sentence earns its place; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool, the description covers the essential access prerequisite and the lookup key. The lack of an output schema is partially mitigated by the clear verb and resource, though it would be marginally stronger with a note about the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 reference_id as 'Your unique reference ID.' The description adds the 'your unique identifier' framing, which reinforces meaning but does not significantly expand beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a verification request by its reference ID' with a specific verb and resource, and clarifies that the reference ID is 'your unique identifier.' This is precise about what the tool does, though it does not explicitly differentiate from sibling tools like get_verification_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical access guidance: a Proof account is required, PROOF_API_KEY must be set, the server must be restarted, and start_login does not open this tool. This provides clear context and an explicit exclusion, though it does not compare usage against alternative get/list verification request tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It clearly discloses the access requirement (Proof account, PROOF_API_KEY, or start_login session), and 'List' implies a non-destructive read. It does not mention return shape, pagination, or whether only pending requests are returned, leaving some behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the purpose front-loaded and the ACCESS prerequisite clearly separated. It is efficient, though the authentication sentence is slightly verbose and could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument list tool with no output schema, the description covers the essential purpose and access. However, it leaves important context unstated: how this tool relates to list_verification_requests and list_my_requests, what an 'incoming verification request' includes, and what the response contains. This is a minimum-viable description with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is complete (100% coverage). Per the rubric, a zero-parameter tool gets a baseline of 4; the description does not need to document parameter syntax or semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a specific resource ('incoming verification requests') and a clear scope: only requests where the authenticated user is the subject. This scope distinguishes it from sibling list tools such as list_verification_requests and list_my_requests without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose sentence implies when to use the tool, and the ACCESS block gives prerequisites, but there are no explicit when-to-use or when-not-to-use instructions versus sibling tools like list_verification_requests or list_my_requests. The only usage guidance is about authentication setup, not selection among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly implies a non-mutating operation by saying 'before saving' and describes the output as a rendered preview. It also discloses a meaningful behavioral quirk: start_login does NOT open this tool, and an API key must be set. This is valuable transparency, though it could be more explicit about side effects or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a useful access note. The sentences are efficient, though the phrase 'with sample data' and 'placeholder variables filled in' are slightly redundant. The access block is clear and actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, timing, and access, and the schema handles parameter details. However, there is no output schema and no explanation of what the returned preview looks like. It also does not clarify how this tool differs from closely named siblings like preview_template or render_template, which an agent would need to route correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds some contextual meaning by mentioning 'placeholder variables filled in', which helps understand body and button fields. It does not, however, add per-parameter detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Preview a profile template') and the resource, making the tool's function obvious. It also explains what the preview does: 'Shows how the message will look with placeholder variables filled in.' However, it does not explicitly differentiate this tool from sibling tools like preview_template or render_template beyond the word 'profile.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit timing context: 'before saving' indicates when this tool should be used. It also provides important access guidance, explaining that a Proof account with PROOF_API_KEY is required and that start_login does not grant access to this tool. It stops short of naming alternative tools or specifying when not to use this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral burden. It does disclose a status constraint and an access requirement beyond what the schema shows. However, it does not mention irreversibility, downstream effects on the authorization, or the result/error shape, so it only partially covers the mutation's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the action and resource, and the ACCESS note is compact and relevant. The only minor flaw is that 'Only authorizations with status active or pending...' restates the constraint already present in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two scalar parameters and no output schema, and the description covers prerequisites and valid statuses. Still, without annotations or an output schema, an agent is left without information about side effects, return behavior, or error cases, so completeness is adequate but not strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds context that the target must be an active or pending authorization, but it does not explain the reason field beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names the specific action and resource: 'Revoke an active or pending authorization.' The status restriction clarifies the operation and distinguishes it from generic revoke tools. This is a clear verb-plus-resource statement that stands apart from the sibling revoke_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the only valid statuses ('active' or 'pending') and gives operational prerequisites: Proof account, PROOF_API_KEY, and a server restart. It also warns that start_login does NOT open this tool, preventing an obvious wrong authentication path. It does not name alternative revoke tools such as revoke_auth_session, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the main side effect ('Replaces the default template'), the auth requirement (Proof account/API key), and warns against the start_login path. It does not state whether an existing custom template is overwritten or what the response looks like, but the core behavior and access constraints are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences: the first defines the operation and side-effect, and the second gives only the necessary access note. There is no filler, and the access warning earns its place because it prevents a likely wrong invocation path.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the operation, the target (channel + message type), the side effect, and how to enable access. It does not mention the return payload or what happens if a custom template already exists, but the schema covers the inputs and the essential setup step is explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all six parameters including channel enum, message_type, body, subject, button_text, and button_url_template. The description only repeats channel and message_type in prose and adds no format or syntax details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'Create or update' with resource 'custom template for a specific channel and message type,' and adds the key side-effect 'Replaces the default template.' This clearly identifies the operation and roughly separates it from sibling template tools, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete access prerequisite ('Set PROOF_API_KEY and restart this server, then call this tool again') and a useful exclusion ('start_login does NOT open this tool'). However, it gives no explicit guidance on when to choose this tool over sibling template tools like list_templates, get_template, or update_profile_template, so the usage context is mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and it does well, disclosing that the tool checks signature, expiry, and revocation status server-side, and optionally validates the identifier. It also reveals the public endpoint nature, adding useful behavioral context. It doesn't mention response details, but the core behavior is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with the primary action front-loaded. The second sentence adds the key validation details, and the third notes the auth requirement. Every sentence earns its place with no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter validation tool with no output schema, the description covers the main operation and the public-auth requirement. Parameter details are fully handled by the schema. The only minor gap is the lack of explicit return-value information, but this doesn't prevent an agent from calling the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with proof_token and identifier already well-documented. The description adds no additional parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Validate' with the resource 'proof token' and lists the exact checks performed (signature, expiry, revocation status). It is clear and unambiguous, though it does not explicitly differentiate from sibling tools like get_proof_status or verify_delegation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when full validation of a proof token is needed by listing the checks, and notes it is public with no API key required. However, it does not explicitly state when to use this tool versus alternatives, nor does it give exclusions or comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the authentication prerequisite and that the username is unique, but it does not explain failure behavior for an already-taken username, whether claiming replaces an existing username, or what the response indicates. This is partially transparent but leaves important edge-case behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action, plus a separate ACCESS note for authentication. It loses a point because the username validation rule is duplicated from the schema, but the overall structure is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description provides the essential context: what is claimed, for whom, the constraints, and how to authenticate. It lacks explicit error/return-value details, but the agent has enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the username parameter completely with type, pattern, min/max length, and a description. The tool description essentially repeats these constraints rather than adding new semantic meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Claim a unique username for the authenticated user's public profile.' This clearly states the action, the object, and the scope, distinguishing it from the large sibling set. The uniqueness and character constraints add useful precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool is usable: the user must have a Proof account, and the agent must either set PROOF_API_KEY or complete sign-in via start_login before calling. It does not explicitly name alternatives, but none of the siblings directly compete with this action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does add useful auth/setup context beyond the basic action. However, it does not disclose side effects, profile limits, default behavior for is_primary/is_public, or what happens on repeated calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences carry the essential information. The main action is front-loaded, and the access prerequisite is cleanly separated into a second block without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested theme object, 8 optional parameters, no output schema, and no annotations, the description leaves operational outcomes unexplored such as return values, default primary/visibility state, and profile creation limits. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only lists some field groups as optional and adds little semantic meaning beyond the schema. It also does not clarify relationships like is_business with business_name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('new profile'), and enumerates the optional fields. This clearly distinguishes it from sibling tools like update_profile, get_profile, and delete_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit access guidance: needs a Proof account, PROOF_API_KEY must be set, and start_login is not the path to this tool. It doesn't explicitly mention update_profile as the alternative for existing profiles, but the create-vs-update context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that deletion is actually an archive operation that sets status to archived, and explains the result that new confirmations cannot be created afterward. It also transparently documents auth requirements and the fact that start_login is not a valid access path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and front-loaded with the core action and consequence. The access note is somewhat verbose but earns its place because it prevents a common failure mode involving authentication. No redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description adequately covers the action, side effects, and access requirements. It could mention whether archiving is reversible or what the response contains, but the missing details are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the only parameter 'id' is already documented as 'HITL config ID to delete.' The description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb and resource: 'Delete (archive) a HITL config.' It further clarifies the semantics by saying 'Sets status to archived' and adds the key consequence that it cannot be used for new confirmations after deletion. This distinguishes it from sibling tools like update_hitl and get_hitl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides access prerequisites: needs a Proof account, set PROOF_API_KEY, and restart the server. It also explicitly says 'start_login does NOT open this tool,' which is an exclusion. However, it does not mention when to prefer delete_hitl over alternatives like update_hitl or how to reverse the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the auth/session requirement and that only pending verification requests are eligible. However, it does not say how much the expiration is extended, whether repeated extensions are allowed, or what happens after the extension, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is concise and immediately conveys the tool's purpose. The access note is relevant and earns its place, though the phrasing 'sign in with start_login — a session opens this tool — then call this tool again' is slightly more verbose than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one fully documented parameter and no output schema, the description covers the core purpose, the pending-request constraint, and authentication requirements. The main gap is the lack of detail about the extension duration or effects, but the tool is simple enough that this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter, describing 'id' as the 'Verification request ID to extend.' The description reinforces the request context but adds no new parameter-level meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Extend the expiration time of a pending verification request.' This clearly distinguishes it from sibling tools like cancel_verification_request, get_verification_request, or wait_for_request by focusing on the extension of expiration rather than creation, retrieval, cancellation, or waiting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: the request must be pending, and the tool extends its expiration time. It also explains the authentication prerequisites for access. However, it does not explicitly contrast this tool with alternatives or state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool returns the stored publishable token plus a derived effective_status/is_valid, and explains the invalidation logic involving control proof status and expires_at. This is substantive context beyond a simple 'get'. It doesn't explicitly assert read-only behavior, but 'Get' reasonably implies no mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in a clear opening sentence. The following sentences about derived status and access requirements are valuable and not redundant. The ACCESS note is actionable and compact. It is slightly verbose in the derivation explanation, but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter get tool with no output schema, the description explains what is returned, the semantics of the derived fields, and the auth prerequisite. It doesn't detail error cases or exact response formatting, but it conveys the essential information an agent needs to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single id parameter, including the pattern and a description. The description mostly restates the two allowed id forms, adding only the ownership nuance ('one of your delegations'). This is a baseline 3 because the schema does the heavy lifting and the description adds minimal extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action: 'Get one of your delegations by Mongo id or ph_dlg_* handle.' This names the verb, the resource, and the retrieval mechanism. It distinguishes itself from sibling tools like list_delegations by targeting a single delegation and from revoke_delegation/verify_delegation by being a plain fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: you need a Proof account, must set PROOF_API_KEY, and start_login does not open this tool. It also implies you use it when you already have a delegation id or handle. However, it does not explicitly contrast with alternatives such as list_delegations or verify_delegation, so the when-to-use guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It meaningfully discloses the return contents, the conditional presence of the proof token ('once confirmed'), and the polling semantics. It also adds a non-obvious access gotcha about start_login not opening the tool. This is solid for a simple read/poll operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core operation and return information are front-loaded in the first sentence, with 'Poll this for resolution' immediately after. The ACCESS note is separated and contains important setup information without padding. It is slightly longer than strictly necessary but every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required parameter, no nested objects, no output schema. The description covers purpose, response contents, and polling behavior, which is enough for an agent to select and call it. It does not enumerate possible status values or error cases, but that is a minor gap for this low-complexity getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter documented as 'Identity challenge ID' and constrained by a hex pattern. The description only says 'by ID,' which adds no new semantics beyond the schema. The baseline of 3 applies because the schema already handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a Proof-Me identity challenge by ID.' It also lists what the call returns (status, channel, proof token), making it clear this is a retrieval/polling operation. It does not explicitly contrast itself with sibling getters like get_confirmation, but the identity-challenge scoping is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Poll this for resolution' gives clear context for when to use this tool: after obtaining an identity challenge ID, call this repeatedly until resolved. The ACCESS note further clarifies prerequisites and that start_login does not unlock this tool. It stops short of naming alternative tools or explicit when-not-to-use conditions, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses the Proof account requirement, the need to set PROOF_API_KEY and restart the server, and that the hitl_channels sub-object requires hitl:read scope. It doesn't explicitly state read-only nature, but 'snapshot' implies it, and the access constraints add meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a dense but clear list of contents, followed by a short contextual line and a compact access block. Every sentence serves a purpose, though the first sentence is long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description covers what the tool returns, access prerequisites, and a scope requirement. It doesn't describe exact output field names or error behavior, but the listed contents are enough for an agent to decide and call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single optional environment enum. The description doesn't elaborate on the parameter, but the schema fully documents it, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('Get a one-call account snapshot') and enumerates the exact contents: quota with projection, request health, per-channel completion, HITL counts, and active API key count. The phrase 'same data the dashboard home renders' contextualizes the scope, though it does not explicitly name a sibling alternative for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It positions the tool as the consolidated one-call snapshot versus more granular tools, and the access note clarifies that start_login does NOT open this tool and that PROOF_API_KEY must be set. It doesn't explicitly state when to prefer a sibling, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It usefully discloses the API key prerequisite, the need to restart the server, and the fact that start_login will not unlock this tool. However, it does not state whether the call is read-only, what happens on missing/invalid credentials beyond setup, or what error/response behavior to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the purpose and return contents, and the second sentence provides essential access guidance. Every sentence earns its place with no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-style tool with no output schema, the description is reasonably complete: it names the returned subscription fields and explains the access setup needed. It could additionally describe failure modes or the exact response shape, but the essential calling context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The schema is empty and the description correctly focuses on return content rather than parameter meaning. There is nothing more the description needs to explain about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets current subscription details and enumerates the included fields: plan, status, billing period, and usage limits. It is specific about the resource and what is returned, though it does not explicitly differentiate itself from overlapping siblings such as get_usage or get_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear precondition: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted before calling again. It also warns that start_login does NOT open this tool, which is an explicit when-not. It does not name alternative sibling tools for similar subscription/usage data, stopping short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of explaining behavior. It frames the operation as read-only status retrieval and adds relevant access constraints, including the need for a Proof account and API key or login session. While it does not explicitly state 'no side effects,' the 'Get current status' wording makes the operation's nature sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a distinct ACCESS note. Each sentence adds necessary information. The phrasing 'a session opens this tool — then call this tool again' is slightly awkward but still understandable and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter status getter with no output schema, the description covers the main invocation needs: what the tool does, what it returns at a high level, and what authentication prerequisites exist. It does not describe possible status values or where the session_id originates, but the low complexity makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter, session_id, is already documented as 'Domain verification session ID.' The description does not add meaningful extra semantics beyond reinforcing that this relates to a domain verification session. Baseline 3 is appropriate because the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get the current status of a domain verification session, including challenge details.' This is clear and informative. However, it does not explicitly differentiate itself from closely related siblings like check_domain_verification or get_verification, relying mostly on the tool name for distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The ACCESS note provides concrete usage context: a Proof account is required, and the agent can either use PROOF_API_KEY or go through start_login and then call this tool again. This gives clear preconditions and a sequencing hint, though it does not explicitly state when not to use this tool or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden of behavioral disclosure. It does well by indicating this is a non-saving preview, showing that sample data is used, and describing the auth requirement. It does not explicitly state that no message is sent or that no template is persisted, but 'before saving' strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then gives actionable access guidance. It is compact, but the first two sentences are slightly redundant ('Preview a template with sample data' and 'Shows how the message will look with placeholder variables filled in'), and the access instructions take a few extra words than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-mutating preview tool with a fully documented schema, the description covers the essential points: what it does, when to use it, and what authentication is required. It does not explain the output format or explicitly route agents to render_template for saved templates, but those gaps are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with meaningful descriptions for every parameter and enums for channel and message_type. The description adds only general context about placeholder variables and sample data, not parameter-specific guidance 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Preview a template') and the resource, and explains the output: how the message will look with placeholder variables filled in. However, it does not distinguish preview_template from sibling tools like render_template or preview_profile_template, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by saying 'before saving' and provides explicit access prerequisites: a Proof account, PROOF_API_KEY, and a server restart. It even warns that start_login does not open this tool. It does not explicitly name alternative tools or when to use them instead, leaving a small gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose authentication requirements (needs a Proof account, PROOF_API_KEY or start_login), which is valuable. However, it does not mention rate limits, whether the previous OTP is invalidated, or behavior on invalid/expired sessions, leaving notable gaps for a side-effectful resend operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is a tight, front-loaded statement of purpose. The access note is slightly verbose but necessary for practical invocation. Overall, every sentence earns its place; it is informative without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter and no output schema, so complexity is low. The description covers what it does and the required access setup. It could be more explicit about deriving session_id from start_add_email, but 'Add-email session ID' plus 'in-progress email addition' provides adequate context for an agent to infer the correct flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the single parameter session_id is already described as 'Add-email session ID.' The description adds no additional parameter semantics beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and object: 'Resend the OTP code for an in-progress email addition.' This clearly identifies the action and resource, and distinguishes it from siblings like verify_email_otp (which verifies the code) and start_add_email (which starts the process).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for an in-progress email addition' gives clear context for when this should be used: after an email addition has been initiated and when a code needs to be resent. It does not explicitly name alternatives or exclusions, but the 'in-progress' constraint is a strong usage signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It discloses the key behavioral side effect (previous primary becomes secondary) and the access restriction that start_login does not open this tool. It does not discuss reversibility, failures, or response shape, but the essential mutation behavior is transparent for a simple one-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the primary action and side effect. The ACCESS block is terse and slightly unusual with the server-restart instruction, but it contains no filler and every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation with no output schema, the description covers the action, the side effect, and the access prerequisite. It does not describe return values or error conditions, but the tool is simple enough that these are acceptable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and profile_id is already described as 'Profile ID to set as primary.' The description adds no extra detail about parameter constraints, formatting, or validation, so it stays at the baseline for fully documented schema parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action and resource: 'Set a profile as the primary profile.' It also explicitly discloses the side effect that the previous primary profile becomes secondary, clearly distinguishing this from generic profile updates and from sibling primary setters like set_primary_email or set_primary_phone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use the tool, and the ACCESS note provides a prerequisite (Proof account with PROOF_API_KEY set). However, there is no explicit guidance about when to choose this tool over alternatives such as update_profile or set_primary_email, and no mention of conditions where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It does disclose that this is a mutation of the current user's profile and that it requires prior Proof account setup. However, it does not clarify whether omitted fields are preserved or overwritten, what side effects occur, or what the operation returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states purpose and supported fields, while the ACCESS note is separated and directly actionable. There is no redundant wording, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 8 optional parameters, nested objects, and no output schema, the description covers the core purpose and access requirements. However, it does not explain partial-update semantics, return values, or error behavior, leaving the agent to infer important invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the structured schema already explains every parameter, including nested theme and custom_links fields. The description only broadly lists the supported categories without adding constraints, defaults, or merge behavior, so it meets the baseline but adds no meaningful semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Update the current user's primary profile,' which clearly distinguishes this from sibling tools like update_profile (which suggests updating a profile by ID rather than the caller's own primary profile). It also enumerates the supported fields, making the tool's scope immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to modify the signed-in user's primary profile. The ACCESS note adds important usage prerequisites by requiring a Proof account and a configured PROOF_API_KEY, and explicitly warns that start_login does NOT open this tool. It stops short of naming alternative tools such as update_profile for non-primary profiles, so it is not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It usefully discloses the Proof account requirement and the need to either set PROOF_API_KEY or complete start_login. However, it does not disclose side effects, whether verification is synchronous or asynchronous, or what happens on failure, which leaves behavioral transparency only partially addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in one sentence, and the usage condition comes immediately after. The ACCESS block is somewhat verbose but provides necessary authentication context for making the tool usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool, the description covers what the tool does, when to use it, and the authentication requirements. It does not describe return values or failure modes, but the simplicity of the tool and the complete schema make this a minor gap rather than a blocking one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the single parameter with a clear description: 'Domain ID to verify.' Since schema description coverage is 100%, the description does not need to add parameter-level detail, and the contextual phrase 'pending domain' adds a little extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Verify a pending domain using previously stored DNS credentials.' It also distinguishes itself from the generic sibling verify_domain by specifying the precondition 'credentials are already connected,' so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly gives the usage condition: 'Use when credentials are already connected.' It also explains the authentication prerequisite and how to recover from an unauthenticated state, but it does not explicitly name an alternative tool to use when credentials are not connected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden and does a good job: it warns that credentials will be visible in the AI conversation context and explains the access/session requirement. It falls short of fully describing the outcome or failure behavior, but the key side-effect and prerequisite are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose is stated first, followed by a high-value privacy warning and the access prerequisite. Every sentence earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the fully documented schema, the description provides enough context for correct invocation, including prerequisites and a notable privacy concern. It could be slightly stronger by pointing to get_dns_providers or describing the expected result, but those are minor omissions rather than critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with clear descriptions, giving 100% schema coverage. The tool description adds only the context that the provider is for verification and that credentials are sensitive, which is helpful but does not materially expand parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add an additional DNS provider') and the target resource ('already-verified domain'), which makes the tool's purpose easy to understand. It does not explicitly name or contrast with sibling tools like connect_dns_provider, so it misses the strongest form of differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for already-verified domains and requires a Proof account, with explicit setup or login instructions. It does not include when-not-to-use guidance or name alternatives, but the context is specific enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the key precondition (pending status) and the auth/access requirement. However, it does not describe side effects, whether cancellation is irreversible, or what happens if the request is already in a different state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core action, followed by the state constraint and access note. Every sentence carries useful information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter cancel operation, the description covers the main state prerequisite and an unusual access requirement. It could add return/error behavior, but the core information an agent needs to call it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'id' parameter as a 'Verification request ID', so schema coverage is 100%. The description adds no additional parameter-level meaning, but the baseline of 3 applies because the schema already handles it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Cancel') on a specific resource ('verification request') with a clear state qualifier ('pending'). This cleanly distinguishes it from related sibling tools like create_verification_request, get_verification_request, and cancel_user_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit conditions: only pending requests can be cancelled, and a Proof account with PROOF_API_KEY is required. It also warns that start_login does not grant access to this tool. It does not mention alternative cancellation tools, but gives enough context to avoid obvious misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure, and it does a good job: it explains the prerequisite account/API-key setup, that the server must be restarted, and that user approval is required before confirmations can be sent. It does not detail every side effect or response, but the key behavioral expectations are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, leading with the core action and purpose, then adding access requirements and a critical caveat. Every sentence serves a purpose, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter create tool with no output schema and no annotations, the description covers the essential context: what an authorization is, how approval works, and the access prerequisites. It does not describe return values or next steps after creation, but the schema handles parameter details and the approval lifecycle is sufficiently explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds conceptual context like 'via a specific channel' and 'business name displayed to user,' which lightly reinforces channel and business_name, but it does not add meaningful parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create a new authorization request') and clearly defines the resource: authorizations grant permission to send confirmations via a channel. It also distinguishes itself from confirmation creation by noting the user must approve before confirmations can be sent, which separates it from sibling tools like create_confirmation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful setup context (requires a Proof account, API key, server restart) and implies when the tool should be used, but it does not explicitly name alternatives or state when to choose this over related authorization tools. The 'start_login does NOT open this tool' note is an exclusion, but it is more about environment setup than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by warning that credentials will be visible in the AI conversation context, which is a critical side effect, and it explains the account/auth requirements. It does not mention overwrite behavior or validation details, but the security and access disclosures go beyond the bare minimum.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose appears first, followed by the important privacy warning and a concise access note. Every sentence contributes useful information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter creation tool with no output schema and no annotations, the description covers the core purpose, critical privacy implications, and access requirements. It could be slightly stronger by noting what a successful call returns or how this step connects to later verification tools, but overall it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both required parameters fully, including provider examples and the format for credentials as key-value pairs. The description adds little parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Store'), a clear resource ('DNS provider credentials'), and a purpose ('automated domain verification'). It clearly conveys what the tool does, though it does not explicitly differentiate it from sibling tools like connect_dns_provider or connect_cloudflare.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: storing DNS provider credentials for automated domain verification. It also provides explicit access prerequisites and authentication steps. However, it does not specify when not to use this tool or point to alternatives like list_dns_credentials or verify_domain_with_credentials.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It explicitly warns 'This cannot be undone,' which is critical for a destructive operation, and explains the auth access model via PROOF_API_KEY or start_login. It does not detail side effects on associated resources, but the key hazards are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, irreversibility warning second, and access instructions last. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description provides enough to invoke safely: what it does, that it is irreversible, and how to authenticate. It omits minor conveniences like how to obtain the domain ID, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the only parameter 'id' with the description 'Domain ID to delete', and coverage is 100%. The description adds no further parameter meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('remove'), resource ('domain'), and scope ('from the account'), making the tool's function immediately clear. It also distinguishes itself from domain-related siblings like add_domain, verify_domain, and get_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool — when a domain should be permanently removed — and clearly states authentication prerequisites. However, it does not explicitly mention alternatives or when not to use this tool, so some guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses an important operational limit (maximum 10,000 records), the output formats, and the access setup, including that start_login will not satisfy authorization. It does not describe return shape or behavior beyond the limit, but it covers the main gotchas.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences cover the core function and filters before an equally tight access note; the ACCESS block is terse but necessary. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read/export tool, the description covers purpose, formats, filters, record limit, and a non-obvious authentication prerequisite. The main gap is the absence of any statement about the response/return value, but with no output schema and a straightforward export action, this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters and their formats/enums (100% coverage), so the baseline applies. The description only restates that date-range and status filtering are supported; it adds no new parameter-level detail, though the 10,000-record cap is a useful global constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact operation: export authorizations to CSV or JSON. The supported filters and record cap sharpen the scope, and although it does not name sibling tools, the export format and resource make it clearly distinct from list_authorizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for calling it: when an export of authorizations with optional date/status filters is needed. It also gives an explicit negative routing note: start_login does NOT open this tool, and a precondition: set PROOF_API_KEY and restart the server. It does not name list_authorizations or export_data as alternatives, so it stops short of full sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It covers auth requirements (Proof account, PROOF_API_KEY, start_login), the polling workflow, and the meaning of each return state. It does not explicitly state it is read-only, but the wording strongly implies a non-mutating status check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded summary, an agent-usage paragraph, and an access note. Every section serves a purpose, though the polling instruction is slightly redundant ('Poll this' and 'Check every few seconds'). Overall it remains compact and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully explains the meaningful return states and what the agent should do in each case. It also covers prerequisites, authentication setup, and the relationship to start_2fa. For a simple one-parameter polling tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter with a clear description ('2FA session ID'), so schema coverage is 100%. The description adds contextual meaning by indicating the session comes from start_2fa and how status values should drive behavior, but it does not introduce new parameter-level details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Check the status of a 2FA session by session ID.' It also enumerates the possible outcomes (completed, pending, expired). It does not explicitly contrast with the sibling wait_for_2fa, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: poll after start_2fa, check every few seconds, and react based on terminal states. It also explains what 'pending' means. It does not mention when to use wait_for_2fa instead, so exclusion guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses access requirements and polling behavior, which is useful. However, it does not define what terminal states look like, whether the operation is read-only, or what happens when the session_id is invalid or expired.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the core purpose, the second gives the polling behavior, and the final access note is operationally necessary. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter polling tool with no output schema, the description covers purpose, polling behavior, and access requirements. It does not explicitly link session_id to start_add_phone or enumerate terminal states, but those are reasonably inferable from the tool name and the 'in-progress' qualifier.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes session_id as 'Add-phone session ID' with 100% coverage. The description only restates 'by session ID' and adds no additional format, source, or constraint information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Check the status of an in-progress phone addition by session ID.' This clearly identifies the tool's function and distinguishes it from related tools like get_add_email_status or start_add_phone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Poll until terminal state,' which tells the agent how to use the result. It does not explicitly name alternatives or say when not to use it, but the in-progress phone addition context implies it should be called after start_add_phone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses pagination, the Proof-account requirement, the need to set PROOF_API_KEY and restart, and that start_login is not a sufficient access path. It does not cover error behavior or response shape, but for a read-only listing operation this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficient: one clear purpose statement followed by a necessary access caveat. There is no filler, and the most important operational warning is separated and easy to act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functional behaviors—optional filtering and pagination—plus the critical environment prerequisite. Since there is no output schema, a bit more detail about the response envelope could help, but the information needed to call the tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five optional parameters in detail. The description's phrase 'optional filters' adds little beyond the schema, keeping this at the baseline score for well-covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('authorizations'), adds that filters are optional, and notes paginated results. It is clear about what the tool does but does not explicitly differentiate it from sibling tools such as list_auth_sessions or get_authorization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete access preconditions: a Proof account is required, PROOF_API_KEY must be set, the server must be restarted, and the tool should be called again afterward. It also warns that start_login does not open this tool, providing a useful when-not signal, though it does not compare against sibling listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states an important privacy/security behavior: an identifier is NEVER returned, and each member only has has_telegram and has_whatsapp booleans. It also reveals auth setup behavior. It omits details like pagination or exact response shape, but the key behavioral constraints are explicitly surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the primary purpose appears first, followed by the critical output constraint, then actionable access instructions. Every sentence earns its place, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description supplies a useful picture of the return shape by stating that each member carries only channel-presence booleans and never an identifier. It also covers the required auth context. It is slightly light on what an agent should do if it needs full member identifiers, but the description is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter and describes it as 'Circle ID.' The description adds no additional semantic detail about the id beyond what the schema already provides, so the baseline score of 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'List a Circle's members.' It adds meaningful scope by specifying that only channel-presence booleans are returned and that identifiers are never included. It does not explicitly distinguish itself from sibling member-related tools, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear access prerequisites: a Proof account, PROOF_API_KEY, server restart, and a follow-up call. It also explicitly warns that start_login does not open this tool, which prevents a likely misuse path. It does not compare against sibling tools for retrieving member details or channels, so alternatives are not explicitly named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the read-only listing nature, the returned ordering by channel and message type, and the merge with defaults. It also surfaces the API-key/account requirement and clarifies that start_login is not sufficient. It doesn't specify failure modes or rate limits, but for a simple list tool this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a one-sentence purpose, a one-sentence output summary, and an access note. Each line adds information, and there is no repetition of schema fields or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only list operation with no output schema, the description covers what the tool returns, its scope, and its auth prerequisite. It might benefit from an example or explicit error behavior, but nothing is critically missing for invoking it with a valid profile_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents profile_id as a required string with the description 'Profile ID', and schema coverage is 100%. The tool description only repeats that this is about a profile and adds no format, source, or validation detail. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb and resource: 'List all templates for a profile.' It adds output structure ('organized by channel and message type, merged with defaults') that distinguishes it from generic template tools such as list_templates and get_default_templates. However, it does not explicitly name alternatives, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete access prerequisites: 'needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again.' It also explicitly rules out start_login as a way to open this tool. Yet it does not state when to prefer this over list_templates or get_default_templates, so no sibling routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that the tool generates and sends a new code, is email-only, requires a Proof account and PROOF_API_KEY, and is not opened via start_login. It does not mention side effects like invalidating previous codes or rate limits, but the core behavior and prerequisites are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose, followed by a short access note. Every sentence serves a purpose, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers the essential invocation details: action, effect, channel, prerequisite, and a relevant exclusion. It could briefly mention what the caller should expect in return, but that is a minor gap given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter, id, as 'Verification ID', so schema coverage is 100%. The description adds no additional meaning about how to obtain the ID or what format it should take, so it stays at the baseline for well-covered schema parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: it resends a verification message and generates/sends a new code. It also scopes itself to email-only, which helps separate it from multi-channel verification tools, though it does not explicitly name or contrast a sibling like resend_email_otp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context and exclusions: email channel only, requires a Proof account, and start_login does NOT open this tool. It does not name an alternative tool to use instead, but the conditions and non-goals are explicit enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosing behavior. It does explain the access/auth requirement and the need to retry after creating a session, which is useful. However, it does not disclose side effects such as what happens to the previous primary email, whether verification is required, or what the success/failure response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a clearly marked access note. Every sentence adds necessary information, and there is no redundancy with the schema or the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation with no output schema, the description covers the main action and the critical auth precondition. It could be slightly more complete by pointing to list_emails for retrieving the email record ID or mentioning whether the email must already be verified, but these are not fatal omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter 'id' is already described as the 'Email record ID to set as primary'. The tool description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set'), the resource ('an email address'), and the scope ('as the primary email for the account'). This distinguishes it from related email tools like list_emails, remove_email, and start_add_email, as well as the sibling set_primary_phone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit preconditions: a Proof account is required, and it explains how to authenticate by either setting PROOF_API_KEY or using start_login. It does not explicitly name alternatives or exclusion conditions, but the access guidance is clear enough for an agent to know when it is ready to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It discloses that the tool creates a verification record, returns DNS/HTTP instructions, requires Proof account access, and is not opened by start_login. This is substantial behavioral transparency, though it could go further by noting idempotency, failure modes, or existing-domain-verification conflicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded: the core action appears in the first sentence, followed by the key outcome and access requirements. Every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with no output schema, the description covers the essential invocation context: what it does, what it returns, and what credentials are needed. It does not explain how to follow up or interpret the returned instructions in detail, but that is reasonably delegated to sibling check/wait tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with descriptions, so schema coverage is 100%. The description adds only slight value by tying the verification_method enum to 'DNS/HTTP instructions' and clarifying the B2B context for customer_id. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Start a B2B domain verification' and specifies that it creates a verification record and returns DNS/HTTP instructions. This distinguishes it from many siblings, though it does not explicitly differentiate itself from closely related tools like verify_domain or create_verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access prerequisites: a Proof account and PROOF_API_KEY must be set, with a restart and retry instruction. It also warns that start_login does NOT open this tool, which provides a useful exclusion against a plausible alternative. It does not, however, discuss when to choose this over other verification-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral disclosure burden. It does state that the tool mutates a profile and controls specific proof display attributes, and it discloses a non-obvious access requirement. It does not, however, clarify whether the provided proofs list fully replaces existing proofs or merges with them, nor does it describe failure behavior for invalid asset IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose is stated in the first sentence, followed by a brief field overview and a clearly labeled access warning. Every sentence contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, a fully documented schema, and no annotations or output schema, the description is largely complete: it explains the operation, the fields it controls, and the authentication prerequisite. The main remaining ambiguity is whether the proofs array is a full replacement or a partial update, which would be useful for an agent to know before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a meaningful description. The tool description's mention of 'visibility, privacy masking, ordering, and labels' adds a concise natural-language mapping to the parameters, but it does not materially enhance what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Update which verified assets (proofs) are displayed on a specific profile.' It further enumerates the controlled aspects (visibility, privacy masking, ordering, labels), so an agent can clearly understand what this tool does and distinguish it from generic profile or verification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: it requires a Proof account, PROOF_API_KEY must be set, and the server must be restarted before retrying. It explicitly warns that start_login does NOT open this tool, which is a valuable exclusion. However, it does not explicitly compare with related sibling tools like update_public_proofs or update_profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains that no code is needed and that the token itself is the proof, and it warns about access requirements. However, it does not disclose side effects (e.g., whether the token is consumed, whether a session is created), nor does it mention prior steps like an active 2FA challenge from start_2fa.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences plus a clearly marked ACCESS section. The core behavior is front-loaded, the differentiator is stated immediately, and access prerequisites are separated. Every sentence earns its place with no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description is largely complete: it states the action, the token input, the access condition, and how it differs from code-based 2FA. The main gap is that it does not explicitly state whether an active 2FA challenge (e.g., from start_2fa) is required before calling this tool, though 'Complete a 2FA challenge' implies one exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – the only parameter 'token' is fully described in the schema as 'Magic link token from the verification email'. The description adds only minor reinforcement ('received via email', 'token itself is the proof') without introducing new semantic detail like token format, expiration, or single-use behavior. Baseline 3 applies given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Complete') and resource ('2FA challenge') and immediately clarifies the mechanism: 'using a magic link token (received via email)'. It also distinguishes itself from the likely alternative by stating 'No code submission needed — the token itself is the proof', which differentiates it from verify_2fa without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you have a magic link token rather than a code. The ACCESS section explicitly states prerequisites (Proof account, API key or prior start_login session). However, it does not explicitly name sibling alternatives or say 'use verify_2fa for OTP codes', leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of behavioral disclosure. It does disclose the access requirement and the conditional outcome ('Completes the add-email flow if the code is correct'), but it does not describe what happens on invalid codes, whether the session is consumed, or any retry/expiry behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the primary action, then adds necessary access context in a separate note. Every sentence contributes useful information, and there is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description gives enough context to call it correctly: it names the operation, the flow it completes, the two required inputs, and the access requirements. It could be more explicit about expected outputs or error cases, but it is largely complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters are already described in the schema: code is the OTP received via email, and session_id is the add-email session ID. The description adds no meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Submit the OTP code to verify an email addition.' It also clarifies the tool's role in the add-email flow, which distinguishes it from generic verification or 2FA related siblings like verify_2fa and submit_verification_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly ties the tool to completing the add-email flow, implying it should be used after receiving an OTP during that flow. It also provides explicit access prerequisites: a Proof account and either PROOF_API_KEY configuration or signing in via start_login. It does not explicitly name alternatives or exclusions, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses polling behavior, exponential backoff with jitter, terminal states, and the access setup requirement. Timeout behavior appears in the schema rather than the description, but overall behavior is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence defines the purpose, the second explains retry behavior, and the final paragraph handles access. Every sentence adds necessary information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter polling tool, it covers purpose, inputs via schema, timeout semantics, terminal states, and access prerequisites. It could have explicitly connected the session ID to a creation tool like create_session, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema already provides; it only adds contextual polling details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Poll a session') and the expected terminal states ('verified, failed, or expired'), so an agent knows what the tool does. It does not explicitly differentiate from sibling wait_for_* tools, though the session focus provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: this is a polling operation for a session, and the ACCESS note provides a concrete prerequisite (Proof account, PROOF_API_KEY, restart). It also cautions that start_login does not open this tool. It stops short of naming alternatives like wait_for_login or wait_for_verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does disclose a critical behavioral trait: 'the API key and secret will be visible in the AI conversation context.' It also states access behavior around sessions. It does not detail side effects such as overwriting existing DNS provider settings, but the key security warning is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the core purpose comes first, followed by the security warning and access requirements. The ACCESS block is slightly dense, but every sentence contributes necessary information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, the description covers the essential operational context: what the tool does, the sensitive credential visibility risk, and the required authentication flow. It does not describe the success response or what happens after connection, but these are secondary given the input schema and clarity of purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a clear description: 'Domain ID', 'GoDaddy API key', 'GoDaddy API secret'. The tool description adds no additional parameter-level detail beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Connect GoDaddy API credentials to a domain for automated DNS record management.' It is immediately distinguishable from similarly named siblings like connect_cloudflare and connect_dns_provider because GoDaddy is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides access prerequisites, explaining that a Proof account is needed and offering two paths: setting PROOF_API_KEY or using start_login to open a session before calling the tool. It lacks an explicit when-to-use versus alternatives statement, but the GoDaddy-specific wording makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It clearly states the action creates a real cross-channel identity challenge, carries the scheduled-safety-check label, and that the account owner practices confirming. It also discloses the API-key requirement and a non-obvious limitation about start_login, which adds meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The action is front-loaded and the access instructions are grouped separately. The phrasing is slightly dense and could be tightened, but each sentence contributes either purpose, usage context, or setup requirements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, target, relationship to automated drills, access prerequisites, and a key operational caveat. The two required parameters are fully documented in the schema. The lack of an output schema means return behavior is not described, but the tool can be selected and invoked correctly from the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters well. The description adds the notion of an 'enrolled member', which slightly clarifies member_id, but it does not meaningfully expand on the parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fire') and resource ('Proof-Me drill') and scopes the action to 'one enrolled member', which clearly distinguishes it from generic sibling tools like trigger_drill. It also contrasts with automated sweeps, making the tool's role evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it: as an on-demand complement to the automated daily drill and monthly reinforcement sweeps. It also provides explicit access prerequisites and warns that start_login does NOT open this tool, giving clear context for when the tool is usable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly states the authentication requirement (PROOF_API_KEY or start_login) and the retry behavior after opening a session. It does not explicitly say it is read-only, but 'Get details' strongly implies a safe retrieval operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in one clear sentence, followed by concise access instructions. The access block is slightly verbose but contains essential operational detail, so every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read tool with one parameter and no output schema, the description is sufficiently complete: it states what the tool returns and how to get access. It does not explain how to obtain a domain ID, but that is reasonably covered by sibling list_domains, and no critical calling information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already fully described in the schema as 'Domain ID', so schema coverage is 100%. The description only repeats the concept of 'by ID' without adding format, source, or additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details of a specific domain by ID') and the resource, and even enumerates the key information returned: verification status, DNS records, and provider connections. This distinguishes it from siblings like list_domains or verify_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' gives clear context: use this when you already have a specific domain ID and want its details. It does not explicitly name alternatives or exclusions, but the access instructions explain how to authenticate and retry after starting a login session, which is helpful usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It honestly discloses the auth dependency and what data will be returned. It doesn't mention side effects, but this appears to be a read-only profile lookup; the access warning is valuable context beyond what the schema alone would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and every sentence earns its place. The access note is separated clearly and avoids bloating the description. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description gives enough context: what it returns and what authorization setup is needed. It could mention the relationship to 'primary profile' versus other profiles, but that is a minor gap and not required for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameter semantics. The description still adds value by stating what the returned profile contains, which is the relevant semantic content here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get the current user's primary profile' and lists what it returns (profile details, theme, custom links, public proof display settings). This makes it distinguishable from siblings like get_current_user and get_profile, though it doesn't explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the required setup: a Proof account, PROOF_API_KEY, and server restart. The note 'start_login does NOT open this tool' is an explicit exclusion that prevents an agent from trying to authenticate via the login flow. It does not describe when to use this tool rather than get_profile or get_current_user, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns only metadata (not secret values), which is a key safety behavior, and explains the authentication requirement. It does not mention potential rate limits or pagination, but for a simple list operation this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded in a single clear sentence, and the access guidance is separated logically. The access paragraph is slightly verbose but still efficient and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, no-output-schema tool, the description covers the essentials: what it lists, what it returns, and how to gain access. It does not enumerate the specific metadata fields, but that level of detail is not required for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and complete schema coverage, so the description needs to add little here. It correctly implies the operation is scoped to the authenticated account, which serves as the implicit filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all API keys'), the scope ('for the authenticated account'), and the output type ('key metadata, not the secret key values'). This distinguishes it from sibling API key tools like create_api_key, revoke_api_key, and get_self_api_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit prerequisite context ('needs a Proof account') and gives concrete steps for authentication via PROOF_API_KEY or start_login. However, it does not mention when to choose this tool over alternatives like get_self_api_key or get_api_key_usage, leaving some routing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It explains the grouping behavior and the unusual authentication requirement that start_login does not enable access. It does not describe pagination details or output shape, but for a simple read-style listing tool this is reasonable coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in a single sentence, and the access note is short but valuable. There is slight redundancy between 'grouped by external_user_id' and 'Shows all verifications per user,' but overall the description is efficient and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two optional pagination parameters and no annotations, the description adequately covers what the tool does and the critical setup prerequisite. It would benefit from a brief note on return format, but that is not essential given the simple list semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes page and limit, including types, constraints, and descriptions, with 100% schema description coverage. The tool description adds no additional parameter meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List verified users grouped by external_user_id.' It also clarifies that it shows all verifications per user, which distinguishes it from flat verification listers like list_verifications and from single-user getters like get_verified_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear access context: a Proof account is required, PROOF_API_KEY must be set, the server must be restarted, and start_login does not open this tool. It does not explicitly compare against alternative tools, but the access guidance is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses the authentication requirement, the need for a Proof account, and the possibility of 2FA verification for sensitive operations. It doesn't detail the response or permanent consequences, but 'remove' clearly implies destructive intent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the primary action. The ACCESS block is useful but slightly verbose; it could be tightened. Overall, every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers the essential context: what the tool does, how to authenticate, and that 2FA may be triggered. It leaves out edge cases like whether the email must not be primary or what the success response looks like, but these are not critical for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes 'id' as 'Email record ID' and marks it required. The description reinforces that removal is by ID but adds no additional semantic detail. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove'), the resource ('an email address'), and the key qualifier ('by ID'). This distinguishes it from related email tools like list_emails, set_primary_email, and start_add_email without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: it requires a Proof account, explains how to authenticate via API key or start_login, and warns that 2FA may be required. It doesn't explicitly name alternatives or exclusions, but the unique remove-by-ID operation makes the intended usage sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does this well by specifying the JWT limitation, the API key capability, and the need for a Proof account with PROOF_API_KEY configured. It does not mention irreversibility or error behavior, but the core behavioral constraints are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it leads with the core action, then gives the critical JWT/API key distinction, then the necessary access setup. The ACCESS section is somewhat verbose but each sentence provides useful information for successfully calling the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and only one parameter, the description covers the essential operational context: what the tool does, how authentication affects behavior, and what environment setup is required. It does not describe return values, but for a revoke operation this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents session_id as 'Session ID to revoke' with 100% coverage. The description adds only that the session is 'specific' and 'by ID,' which does not meaningfully exceed what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Revoke a specific authentication session by ID.' It is immediately distinguishable from sibling tools like list_auth_sessions and get_session because it specifies the revoke action and the targeting by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong contextual guidance, including the JWT/API key distinction and the explicit note that start_login does not open this tool. It does not name alternative tools for when to use them, but it clearly communicates the access prerequisite and the key restriction on revoking the current session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It transparently explains the reverse OTP mechanism, that the system sends a message and the user replies, and details the exact return payload (session ID, deep_link, qr_code, qr_text). It also mentions the auth requirement. It does not cover expiration, follow-up steps, or failure modes, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the tool's purpose and reverse OTP behavior, followed by necessary access instructions. It is slightly long due to the auth note, but every sentence contributes distinct, useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter and no output schema, the description covers the essential return values, the flow, and the authentication requirement. It doesn't explicitly mention the next step (e.g., polling get_add_phone_status), but that is inferable from sibling tool names and not strictly necessary for starting the process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'channel' parameter with an enum (telegram, whatsapp, sms) and a clear description. The tool description adds no additional channel-specific meaning beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Start adding a new phone number.' It also explains the reverse OTP flow and lists the return values, so an agent can immediately understand what this tool does and distinguish it from email or other verification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (when adding a phone number) and provides explicit access prerequisites: requires a Proof account, PROOF_API_KEY setup, or completing start_login first. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does it well: it explains the pending state, the deferred capture of the Telegram chat id, the authentication requirement, and that this tool is not reachable through start_login. It could still disclose return values, idempotency, or duplicate handling, but it is already meaningfully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: purpose first, then workflow, then access prerequisites. Every section contributes useful information and there is no filler, though the ACCESS setup instructions make it slightly longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low parameter complexity and the description covers the core purpose, workflow, next step, and prerequisites. However, with no output schema and no annotations, it omits what the tool returns and does not address edge cases such as duplicate membership or idempotency, which an agent may need to call invite_circle_member correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents id, name, and whatsapp_phone thoroughly. The description adds only mild semantic context by calling the phone 'pre-declared' and framing the member as pending, but it does not materially extend the parameter meanings beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb, resource, and state: adding a pending member to a Circle by name with an optional WhatsApp phone. It also clarifies what this tool does not do by explaining that the Telegram chat id is captured later through a deep link and that invite_circle_member handles the enrollment link, distinguishing it from its sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Agent usage' section gives an explicit workflow directive: after adding a member, call invite_circle_member to mint the enrollment link. The ACCESS block clearly states the prerequisite (Proof account, PROOF_API_KEY, server restart) and warns that start_login does NOT open this tool, providing strong when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly states the downstream impact: 'Domains using this credential will need new credentials for automated verification.' It also explains the session/authentication requirement, giving the agent important preconditions beyond the basic delete action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it opens with the action, then gives the key consequence, then the access requirements. Every sentence adds necessary value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with no output schema, the description covers the core action, the side effect on domains, and the access prerequisite. It could mention how to locate the credential ID (e.g., via list_dns_credentials), but this is a minor gap for an otherwise complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single required 'id' parameter with the description 'DNS credential ID to delete' (100% schema description coverage). The tool description does not add additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb and resource: 'Delete a stored DNS provider credential.' It clearly distinguishes this from sibling tools like create_dns_credential and list_dns_credentials by its destructive, deletion-focused purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool is applicable: removing a stored DNS credential that is no longer needed. It also gives explicit access prerequisites via PROOF_API_KEY or start_login. It does not explicitly name alternative tools or exclusions, but the destructive action and consequence make the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and goes beyond the bare action by explaining the deletion effect (revert to default) and the required authentication state. It does not explicitly say whether deletion is permanent, but 'delete' plus the revert behavior makes the destructive nature clear enough for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the core behavior in the first sentence, and the ACCESS block contains only actionable setup and routing guidance. No sentence is redundant or restates the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter delete operation with no output schema, the description covers the purpose, the auth prerequisite, and the practical blocker (start_login not opening the tool). It could add a pointer to list_profile_templates or update_profile_template, but nothing essential for a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters. The description does not add extra meaning beyond mapping deletion to 'channel and message type,' matching two of the parameters; this is the baseline credit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource ('Delete a custom profile template') and a concrete outcome ('reverting to the default template for that channel and message type'). It is distinguishable from generic siblings like delete_template and update_profile_template by the 'profile template' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear operational context: requires a Proof account, PROOF_API_KEY must be set with a server restart, and explicitly warns that start_login does not open this tool. It does not name alternative tools for choosing between delete_profile_template and related template tools, but the implied use case (restoring default for a channel/message type) is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden and does a credible job. It reveals a notable security guarantee (an identifier is NEVER returned, per SEC-PM-006) and explains the authentication prerequisite and its interaction with start_login. It could go further by detailing error behavior or explicitly confirming read-only semantics, but the provided behavioral context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a single-sentence purpose statement followed by an access/security note. Every sentence contributes essential information, with no repetition or filler, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter get tool with no output schema, the description supplies the essential context: what the response includes, the no-identifier guarantee, and the access prerequisites. It is largely complete for correct invocation, though a slightly clearer statement of what 'presence booleans' means or how errors surface would make it fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter with a description ('Circle ID') and format pattern, so the baseline is 3. The description only repeats 'by ID' without adding extra meaning about the parameter's semantics, constraints, or usage beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('Circle by ID') and clearly states what is returned: the Circle, its members, and per-member channel presence booleans. It also distinguishes itself by noting what is NEVER returned, making its scope unmistakable relative to siblings like list_circles or update_circle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: when you have a specific Circle ID and need the Circle with members and presence data. It also gives explicit access guidance (requires a Proof account, PROOF_API_KEY must be set, start_login does not unlock it). However, it does not name alternative tools or explicitly state when not to use it, such as when listing circles is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It covers authentication behavior (API key + restart) and return contents. It implies read-only semantics through 'Get' and 'Returns' but does not disclose error or not-found behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is short and front-loaded with the operation, then the return summary, then access notes. Every sentence contributes either to invocation or access, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with no output schema, the description covers the returned fields and required setup, which is sufficient for basic invocation. However, it omits error semantics (e.g., invalid/unknown ID) and does not point to list_confirmations for obtaining IDs, so there is a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter completely with 'Confirmation ID' (100% coverage). The description's 'by ID' adds no format, example, or additional meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Get a confirmation by ID', and specifies what is returned ('full confirmation including status, response, and proof token'). It is readily distinguishable from siblings like list_confirmations or wait_for_confirmation because it is a direct fetch by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete access prerequisites: a Proof account, setting PROOF_API_KEY, restarting the server, and retrying. It also explicitly warns that start_login does NOT open this tool, which steers the agent away from the wrong authentication path. It does not explicitly name alternative lookup tools, so it falls short of fully explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It discloses the auth-dependent access requirement and restart workflow, and states what the response includes. It does not explicitly say the tool is read-only, but 'Get' and the return-value phrasing make the non-destructive nature reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: the first states purpose and return contents, the second provides the access prerequisite. No filler or repeated schema information, and the key behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter with no output schema, the description covers the tool's purpose, return contents, and the unusual API-key setup prerequisite. It could be slightly stronger by naming list_hitls as the alternative for browsing configs, but that omission is minor given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter (id) with the description 'HITL config ID', so schema coverage is 100%. The tool description adds little beyond the contextual phrase 'by ID', which matches the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Get a HITL config by ID.' It also clarifies what the config contains ('channels, timeout, and status'), and the 'by ID' framing distinguishes this from list_hitls, which retrieves configs in bulk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful usage context: a proof account is required, PROOF_API_KEY must be set, and 'start_login does NOT open this tool.' This is a clear when-not, but it does not explicitly contrast with list_hitls or state when to use get_hitl versus listing configs, so it is not full 5-level guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden. It discloses the authentication requirement, setup step, and an exclusion about start_login. Since the operation is a getter, the lack of side-effect details is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences/block; the first states purpose, the second gives essential access guidance with no filler. Key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter with no output schema, it explains what is returned and the prerequisite. It could mention error cases, but nothing essential is missing for calling it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes profile_id. The description only reinforces that lookup is by ID, adding no extra format or semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get a specific profile by ID.' It also distinguishes itself from siblings like list_profiles or get_my_profile by emphasizing ID-based lookup and outlines what is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear usage context: requires a Proof account and PROOF_API_KEY, with a restart-and-retry instruction. It explicitly warns that start_login will not unlock this tool, which prevents an obvious wrong path, though it doesn't name alternative getter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden, and it discloses the key selection behavior ('Returns the custom template if set, otherwise the default') as well as the access prerequisite. It does not state read-only semantics or error/return-shape details, but those are less critical for a getter with this much disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the main purpose in the first sentence, and places the access note in a clearly separated ACCESS block. Every sentence earns its place; there is no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter getter with no output schema or annotations, the description covers selection criteria, fallback behavior, and the required auth setup, which is enough for a correct call. A minor gap is that the return structure/format of the template is not described, but this does not impede tool selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents channel and message_type, including valid channel enums and examples for message_type. The description adds the custom/default fallback context but no new parameter-level format or syntax details, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get a specific template by channel and message type,' which makes the tool's function unambiguous. The caveat about custom-vs-default fallback also distinguishes it from list/get_default_* siblings without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage context by warning that a Proof account is required, that PROOF_API_KEY must be set, and that start_login does NOT open this tool—thus excluding an otherwise plausible auth path. It does not explicitly name alternatives like list_templates or get_default_templates, so it misses the top bar of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior itself; it does so by stating the Proof account requirement and that start_login does not grant access. It also conditions the response on verification status ('proof token if verified'). It omits error/not-found behavior, but the core auth and conditional data behavior are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main action is stated in the first sentence, followed by a compact return summary and a short ACCESS note. Every sentence adds information, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter with no output schema, the description covers what the tool returns, the required auth setup, and an important non-obvious access caveat. It does not enumerate all possible response statuses or error cases, but it is enough to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single id parameter at 100% coverage, and the description reinforces that the ID is a verification ID. No additional format, source, or constraints are needed; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get a verification by ID') and clarifies the return payload ('full verification object including status, channel, and proof token if verified'). This distinguishes it from list/request/status siblings at a glance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit access prerequisites ('needs a Proof account', 'Set PROOF_API_KEY and restart this server') and a clear exclusion ('start_login does NOT open this tool'). It does not name alternative lookup tools such as list_verifications or get_verification_request, so routing among siblings is left partly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden of disclosing behavior. It states the authentication requirement, the need to restart the server after setting the API key, and that a previous call may not work until setup is complete. It also clarifies that start_login is not a valid alternative for enabling this tool. It does not describe side effects, but the verb 'get' implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose appears in the first sentence, followed by a terse access note. Every sentence conveys necessary information, and there is no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool, the description covers the purpose, the identifier key, and the critical setup requirement. It does not explicitly state what the response contains beyond 'their verifications,' nor does it mention error cases. Still, the access quirk is unusual and well documented, making the description largely complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes external_user_id as 'The external user ID' with 100% coverage. The description only repeats the concept 'by external user ID' without adding format, source, or example details. Since the schema fully covers the parameter, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Get a single verified user and their verifications by external user ID.' This clearly distinguishes it from the sibling list_verified_users, which retrieves multiple users, and identifies the exact lookup key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit access prerequisites: a Proof account, setting PROOF_API_KEY, restarting the server, and calling again. It also directly warns that 'start_login does NOT open this tool,' which is a useful exclusion. However, it does not contrast with related read tools like list_verified_users or get_verification, so the full decision space is not covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden, and it covers the mutation: it creates a single-use invite and causes the challenger to bind their messenger identity to the config when tapped. It also discloses the auth requirement and the return payload, though it doesn't describe expiration or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well organized: purpose first, then return value, then access prerequisites. No redundant sentences or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description usefully states the returned deep links and QR code, plus the access setup needed before calling. It is adequate for a two-parameter tool, though it could mention that the referenced config/challenger must already exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with descriptions and format patterns, so the description adds no new parameter semantics. The prose references the invite flow but not the IDs themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Mint a single-use Proof-Me enrollment invite for a challenger,' and explains the tangible output (Telegram + WhatsApp deep links, QR code). This differentiates it from sibling tools like add_challenger and start_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly communicates prerequisites: needs a Proof account, PROOF_API_KEY must be set, and the server restarted. It also warns that start_login does not open this tool, giving an explicit exclusion, though it doesn't contrast with other invite/challenger alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool is a state-changing mint that produces a single-use invite, returns Telegram/WhatsApp links and QR, and depends on a server-side API key. Missing details like expiration or revocation are not mentioned, but the core behavioral traits and an operational gotcha are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the main function, followed by a relevant access note. Every sentence adds value; the start_login warning is a worthwhile guard rail rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param tool with no output schema, the description tells the agent what it returns, the side effect (single-use enrollment), and the auth setup required to call it successfully. It does not describe expiration or error behavior, but those are not necessary for selecting and invoking based on the provided schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents 'Circle ID' and 'Member ID to invite' with patterns. The description reinforces the invite purpose but adds no syntax or additional parameter semantics beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action verb ('Mint') and a clear resource ('single-use enrollment invite for a Circle member'), and differentiates itself from siblings like add_circle_member and invite_challenger by emphasizing the messenger-identity binding outcome and returned channel links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit access prerequisites (Proof account, PROOF_API_KEY setup) and a specific routing exclusion: 'start_login does NOT open this tool.' It doesn't enumerate when to prefer this over add_circle_member or invite_challenger, but the context is clear enough for an agent to invoke it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly reveals authentication and access requirements, including that setting PROOF_API_KEY and restarting the server is necessary. It also clarifies a non-obvious boundary: start_login does not unlock this tool. Since this is a read-only list operation, the absence of side-effect warnings is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, and the access prerequisites follow in a clearly separated block. Every sentence adds necessary information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool, the description covers the essential context: what is listed, the scope, and the access prerequisites. It does not describe the output format or pagination, but no output schema exists and the list semantics are reasonably inferable. The access note adds significant completeness beyond the bare schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single parameter hitl_id with type, pattern, and description 'HITL config ID'. The description adds no new parameter-level detail beyond repeating 'HITL config' in the purpose. With 100% schema coverage, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'List the Proof-Me challengers enrolled on a HITL config.' It names a specific verb, resource type, and scope. This distinguishes it from challenger-related mutations like add_challenger, invite_challenger, and remove_challenger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives actionable usage context: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted before calling again. It also explicitly warns that start_login does NOT open this tool, preventing a likely misstep. It does not name alternative list tools, but none directly overlap with this operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers substantial disclosure: archived circles are excluded by default, the status='archived' override, pagination behavior, auth requirements, and a note that start_login will not grant access. This goes well beyond what the schema conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with every sentence earning its place: purpose first, then default behavior/override, pagination, and the access note that prevents repeated failed invocation attempts. No fluff or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the operational essentials for a filter-and-paginate read operation: defaults, override, pagination, and access requirements. There is no output schema, so 'Returns paginated results' is thin on return-shape details, but nothing critical is missing for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3 applies. The description's 'pass status="archived" to surface them' echoes the schema's status description ('archived excluded unless requested') without adding new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (Circles) with optional filters, making its function immediately clear. It is easily distinguished from circle siblings like create_circle, get_circle, update_circle, and list_circle_members, none of which list circles themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete access precondition (Proof account, set PROOF_API_KEY, restart server) and explicitly warns that start_login does NOT open this tool, which prevents a likely misstep. However, it does not contrast against alternatives such as get_circle for a single circle or list_circle_members for membership, so selection among circle-related list tools is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses that results are paginated, supports status and HITL config filtering, requires a Proof account, and requires the PROOF_API_KEY environment variable before use. This meaningfully explains access behavior and avoids a dead-end auth flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds value. The access note is separate and clearly actionable, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with four optional parameters, the description covers the purpose, pagination, filters, and access requirements. It does not describe default page/limit values or the exact return shape, but the absence of an output schema is partially mitigated by the clear 'paginated results' statement and the fully documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description's mention of 'status and HITL config filtering' restates what the schema enum and hitl_id description already cover, adding no new parameter-level semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List confirmations with optional filters', which clearly identifies the verb, resource, and operation. It distinguishes itself from the sibling get_confirmation by using 'list' and by explicitly mentioning pagination and filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool: to list confirmations with optional filters. It also provides important exclusionary guidance: 'start_login does NOT open this tool', preventing the agent from attempting an authentication flow that will not grant access. It does not explicitly recommend alternatives like get_confirmation for single-resource lookup, but the list-versus-get distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses that this is a read-only listing operation, that it returns verification status metadata, and that it requires a Proof account via API key or an authenticated session. This adds meaningful behavioral context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action appears in the first sentence, followed by the return behavior and a focused access note. Every sentence adds useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description covers authentication requirements, account scoping, and the general return shape. It does not explain exact fields or pagination, but these are not critical for a simple list operation, and the access guidance is especially valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already covers everything. With no parameters to document, the baseline of 4 applies, and the description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all domains for the authenticated account.' It also mentions the return content, 'domain metadata including verification status,' which distinguishes it from singular get_domain and mutation tools like add_domain or delete_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for the list action and explicitly explains authentication prerequisites. However, it does not name alternatives or state when to prefer this tool over get_domain or verify_domain. Usage is implied rather than explicitly differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the behavioral burden. The description indicates this is a read-only listing operation and adds important access context, but it does not explicitly state that no changes are made, nor does it describe behavior under missing authentication or empty results. This is acceptable for a simple list tool, but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. It leads with the core purpose in one clear sentence, then provides the necessary access prerequisite in a separate paragraph. No filler or redundant content is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description is largely complete: it states exactly what the tool returns and the access conditions required. It does not specify the return format in detail, but 'list all email addresses' reasonably implies an array of email addresses, and there is no output schema to explain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema describes this completely. With 100% schema coverage and no parameters to clarify, the description does not need to explain parameter meaning; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List all email addresses') and resource ('associated with the authenticated account'). It is easily distinguished from sibling tools like remove_email, set_primary_email, and start_add_email because no other tool claims to list existing email addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool can be used by explaining the authentication prerequisite: a Proof account is required, along with either a PROOF_API_KEY or signing in via start_login. It does not explicitly contrast with alternatives, but no sibling tool offers the same listing functionality, so the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does meaningful work: it discloses an authentication prerequisite, a required environment variable/restart step, and that start_login is insufficient. It also notes pagination behavior. It doesn't cover error cases like missing keys or rate limits, but for a read-only list tool this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose, followed by pagination and access notes. Every sentence earns its place and no terminology is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a low-complexity list operation with four optional, fully documented parameters and no nested objects. The description covers the purpose, pagination, and a critical access requirement that would otherwise cause failed calls. Absence of an output schema makes the return shape less explicit, but 'paginated results' plus the schema is enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage), so the description's phrase 'optional filters' adds no new meaning. Baseline 3 is appropriate because the schema already documents page, limit, status, and environment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'List HITL configs with optional filters' – a specific verb ('List'), a specific resource ('HITL configs'), and the key scope modifier ('with optional filters'). This clearly differentiates it from sibling single-item and mutation tools like get_hitl, create_hitl, and update_hitl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete preconditions ('needs a Proof account', 'Set PROOF_API_KEY and restart this server') and explicitly warns that start_login does not open this tool. However, it doesn't point to the single-item alternative get_hitl for when a specific HITL config is needed, so it misses explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the authentication requirement and the need to retry after establishing a session, which is useful. However, it does not mention return format, pagination, or whether only verified/primary numbers are included, leaving some 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a clearly labeled ACCESS note. Every sentence earns its place, and the structure makes the authentication requirement stand out without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool, the description covers the essential context: what is listed, the scope, and how to authenticate. The absence of an output schema is somewhat mitigated by the clear scope, though a note on the response shape would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so there are no parameter semantics to document. The description appropriately focuses on what is returned rather than input details, and the baseline for zero-parameter tools is respected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('all phone numbers associated with the authenticated account'), making the tool's scope immediately clear. It also differentiates from sibling phone-related operations like remove_phone and set_primary_phone by focusing purely on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The ACCESS section clearly explains the prerequisite: a Proof account, and gives two concrete ways to satisfy it (set PROOF_API_KEY or use start_login). It does not explicitly contrast with alternative list tools, but the context and resource make appropriate usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It discloses the operation type (list with pagination/filtering), the response fields visible, and the authentication setup requirement. This is solid transparency for a read-only list operation, though it doesn't mention error cases or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a necessary access note. Every sentence earns its place, and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description partially compensates by naming the visible fields: 'delivery status, response codes, and timestamps.' Combined with the access prerequisite and fully-covered parameter schema, it gives an agent enough context to invoke the tool correctly. It could go further by describing pagination response shape, but this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters already documented in the input schema. The description mentions pagination and filtering concepts but adds no parameter-specific details beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List webhook delivery attempts with pagination and filtering.' It also clarifies what data is returned ('delivery status, response codes, and timestamps'), making it easy to distinguish from single-delivery tools like get_webhook_delivery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about the access prerequisite: 'needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again.' It also explicitly warns that start_login does NOT open this tool, which is helpful routing information. It doesn't explicitly contrast with list alternatives, but the context is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals an important side effect ('Removing the last challenger disables Proof-Me on the config') and access prerequisites, both beyond what the schema shows. It does not mention reversibility or response format, but the key behavioral traits are clearly stated. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core action and side effect first, then the access setup, then the login exclusion. Every sentence contributes meaningful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool, the description covers what is removed, the disabling side effect, and authentication requirements. It could be slightly more complete by mentioning the expected response or pointing to list_challengers for finding challenger IDs, but those are minor gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters already have descriptions ('HITL config ID' and 'Challenger ID to remove'). The tool description adds little extra meaning about these parameters beyond placing them in the Proof-Me/HITL context, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' with a clear resource ('Proof-Me challenger from a HITL config'), making the tool's purpose unmistakable. It also distinguishes from sibling tools like add_challenger and list_challengers by describing the removal action and the side effect of removing the last challenger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context: a Proof account is required, PROOF_API_KEY must be set, the server must be restarted, and start_login does NOT open this tool. It does not explicitly name alternative tools or when-not-to-use conditions relative to siblings, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses a non-obvious edge case: removing the last channel is allowed and makes the member unreachable. It also exposes an auth prerequisite and clarifies that start_login does not grant access to this tool, which is valuable behavioral context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core operation comes first, followed by the edge-case behavior and the access prerequisite. Every sentence earns its place, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter removal operation with fully documented schema fields, the description is sufficiently complete. It covers the action, the last-channel consequence, and the access setup. The lack of an output schema is not a major gap here because the tool's side effect and success condition are clearly described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions and validation patterns for all three parameters. The description adds no parameter-specific meaning, but this is acceptable because the schema fully documents id, member_id, and channel_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Remove a channel from a Circle member.' It is clearly distinguishable from sibling tools like remove_circle_member and add_circle_member_channel, and the edge-case note reinforces the tool's function without obscuring it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear trigger condition—use when a channel should be removed from a Circle member—and includes an explicit access note that PROOF_API_KEY must be set and that start_login does NOT open this tool. It does not explicitly contrast with alternatives like remove_circle_member, but the implied usage is strong and the access caveat provides useful when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses authentication prerequisites, the need to establish a session, and the possibility of 2FA verification. It does not detail irreversibility or side effects, but 'remove' plus the 2FA warning gives adequate behavioral context for a simple delete-style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action appears in the first sentence, followed by essential access and 2FA context. Every sentence adds necessary information without padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter removal tool with no output schema, the description is largely complete: purpose, parameter, access requirements, and 2FA caveat are all present. It does not mention what happens after removal or whether the removed phone could be a primary phone, but those are edge details rather than critical missing instructions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single 'id' parameter as 'Phone record ID'. The description adds 'by ID' but no additional format, provenance, or usage detail. This is the baseline score when the schema is already complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Remove a phone number from the account by ID.' This clearly distinguishes the tool from siblings like remove_email and list_phones. The purpose is immediately understandable without relying on the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear access context: a Proof account is required, and the user must either set PROOF_API_KEY or sign in via start_login before calling the tool. It also notes that 2FA may be required. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the main side effect—creating a new delivery attempt—and explains the access requirement of a Proof account with PROOF_API_KEY. It does not detail all potential side effects like duplicate attempts or rate limits, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action and its effect, then adds necessary access instructions. There is no filler, and each sentence contributes operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter action tool with no output schema, the description adequately explains what happens, the payload behavior, the endpoint target, and access prerequisites. The only minor gap is that it does not describe the response shape or possible error conditions, but this is not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter, describing id as 'Webhook delivery ID to retry.' The description adds no additional parameter-level detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Retry a failed webhook delivery.' It further clarifies the behavior by stating it 'creates a new delivery attempt with the same payload to the configured endpoint,' which distinguishes it from read-only siblings like get_webhook_delivery and list_webhook_deliveries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies the use case: retrying a failed webhook delivery. It also gives an important exclusion by noting that start_login does NOT open this tool, which prevents an agent from pursuing the wrong access path. It does not explicitly name alternative tools for inspection, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the mutation effect ('marked as revoked'), the downstream consequence ('associated proofs will no longer validate'), and an access prerequisite. It does not mention reversibility or error behavior for already-revoked or non-verified assets, but it provides meaningful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the action and effect appear in the first sentence, followed by a focused access note. Every sentence adds useful information, and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation with no output schema or annotations, the description covers purpose, effect, and access requirements well. It could additionally describe expected responses or error conditions, but the essential information an agent needs to invoke it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter as 'Asset ID' with 100% coverage, so the description adds little new parameter meaning. Saying 'by ID' reinforces which identifier is needed, but the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Revoke a verified asset by ID.' It then states the concrete outcome: the asset is marked revoked and associated proofs no longer validate. This clearly distinguishes it from sibling tools like revoke_proof and list_assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: it requires a Proof account, instructs setting PROOF_API_KEY and restarting the server, and explicitly says start_login does NOT open this tool. It stops short of naming alternatives such as revoke_proof for when a proof, not an asset, should be revoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden and does a solid job: it discloses that the tool sends a verification email to an admin address, requires a Proof account, and explains the API-key vs. login fallback flow. It doesn't mention what happens after the code is sent, but the core side effect and authentication behavior are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action, the second clarifies the effect, and the ACCESS note is separated and directly useful. There is no redundant filler or restated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, full schema coverage, and no output schema, the description covers the essential operational context: what it does, where the code is sent, and what authentication is needed. It stops short of describing the follow-up confirmation step, but the 'start' semantics and sibling tool names make that inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters. The description adds only a general notion of a 'standard admin email address,' which lightly reinforces the email_prefix default but doesn't substantially improve on the enum and descriptions already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Start domain verification via corporate email.' It further says a verification code is sent to a standard admin email address, which clearly differentiates this from sibling domain-verification tools that use DNS, credentials, or provider connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: when starting domain verification over corporate email. It also provides explicit authentication prerequisites (Proof account, PROOF_API_KEY, or start_login). It does not name alternative tools or state when not to use it, but the contextual guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It discloses the test-only restriction, the bypass of real OTP, and the required environment setup. It could go further by stating side effects or irreversibility, but it gives substantial behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact and front-loaded. The key purpose and test-only scope appear in the first sentence; the access setup is separated and actionable. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter test utility with no output schema, the description provides enough context: purpose, test-only constraint, OTP bypass, and access prerequisites. It does not describe the return value or side effects, but is otherwise sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 already documented as 'Verification ID'. The description adds no extra param-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Auto-complete a verification') on a specific resource, with a clear scope ('test mode', 'pk_test_* API keys only'). This differentiates it from production verification flows and sibling tools like submit_verification_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly says when it is useful: testing flows without real OTP delivery. Provides explicit access prerequisites and warns that start_login does not open this tool. However, it does not explicitly compare itself to closely related siblings like trigger_verification or submit_verification_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the access requirement (Proof account, PROOF_API_KEY, server restart) and the fact that start_login is insufficient. It doesn't describe post-call effects or return behavior, but the firing action and prerequisites are clearly surfaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and orderly: the action and scope in the first sentence, context in the second, and access notes in a short paragraph. No filler or repetition; every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description covers the core action, distinguishes it from automated drills, and includes critical setup steps. The main gap is that it doesn't indicate what the caller should expect after the drill is fired, but overall an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters at 100% coverage, so the description doesn't need to repeat them. It adds only the contextual hint that the challenger must be enrolled, which is useful but not a substantial semantic addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Fire') and a precise resource ('an on-demand Proof-Me drill against one enrolled challenger'), and clarifies that it is a real cross-channel identity challenge with the scheduled-safety-check label. This is clearly distinguishable from sibling drill/challenge tools and is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the use case (on-demand drill) and contrasts it with automated daily/monthly drills, and it supplies an explicit prerequisite and restart instruction. It does not name alternative tools to prefer instead, so it stops short of a full when/when-not matrix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden; it discloses the required Proof account and API key setup and warns that start_login does not grant access. It does not detail side effects such as whether channels are replaced wholesale or whether omitted fields are preserved, but the schema already indicates optionality and null-to-clear semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the purpose is front-loaded, and the access warning is separate and unambiguous. No filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter update tool with a fully documented schema, the description covers what is updated and the access requirement. It lacks an explicit note about return values and does not expand the HITL acronym, but that is not critical for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameter meanings. The description adds no new parameter details beyond naming the three changeable categories, keeping it at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Update a HITL config') and enumerates the mutable fields ('name, channels, or timeout'), making the operation unambiguous. It also distinguishes itself from sibling create/list/delete/request tools by focusing only on modifying an existing config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit access prerequisites ('needs a Proof account', 'Set PROOF_API_KEY and restart') and calls out that start_login is not a workaround for this tool. It does not explicitly contrast with create_hitl/delete_hitl, but the verb 'Update' plus field list supplies enough usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals a critical operational trait: authentication is not satisfied by start_login and depends on a server-side PROOF_API_KEY that requires a restart. 'Create or update' also signals upsert behavior, although it does not detail overwrite semantics or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly compact: one front-loaded purpose sentence followed by a necessary access warning. Every sentence carries useful information, and there is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description provides the essential operational context: authentication requirements, retry behavior, and clear scoping by profile, channel, and message type. It could go further by describing return values or explicitly contrasting with update_template, but the schema covers parameter semantics and the access note addresses a major real-world failure mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter descriptions already document body placeholders, channel enum choices, and email-only fields. The tool description adds no additional parameter-level meaning, keeping this at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb phrase, 'Create or update', and a precise resource: a custom template for a specific profile, channel, and message type. This scoping distinguishes it from generic template tools like update_template without needing to name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening sentence makes the tool's usage context obvious: use it when creating or updating profile-scoped templates. The ACCESS note adds a clear prerequisite—requires a Proof account, PROOF_API_KEY must be set before server start, and the tool must be called again afterward—and explicitly warns that start_login does not unlock this tool. It does not explicitly name alternative tools, so it misses a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and uses it well: it discloses the side effect that enabling the first challenger opts the config into Proof-Me, and it explains channel-specific enrollment behavior (telegram captures chat_id later; whatsapp must pre-declare phone). It stops short of describing return values or failure modes, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into purpose, behavioral detail, agent workflow, and access notes, and every sentence adds information. It is slightly longer than strictly necessary, but front-loaded and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description still covers the main behavioral side effects, the required access setup, and the immediate next step. It is missing only minor operational details such as return value/error behavior, so it is strong but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains when whatsapp_phone is required and how channel changes enrollment behavior. This compensates and justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Pre-enroll a Proof-Me challenger (a trusted contact) on a HITL config.' It also distinguishes the tool's role from its sibling invite_challenger by describing the enrollment-link step as a separate follow-up, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit sequencing ('After adding a challenger, call invite_challenger') and an explicit when-not ('start_login does NOT open this tool'), plus a clear access prerequisite. It does not explicitly contrast with remove_challenger/list_challengers, but the workflow guidance is strong enough to place it above a bare context statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses that this is an asynchronous cross-channel approval flow, mentions terminal states (confirmed, denied, expired), and warns that a Proof account and PROOF_API_KEY are required. It does not cover all conceivable side effects, but it gives materially useful behavioral context beyond the name and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The second sentence adds agent-relevant polling behavior, and the third adds essential access context. Every sentence earns its place, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only three parameters, no nested objects, and no output schema, the description is notably complete. It explains the challenge flow, how to consume the result (poll with returned ID), what terminal states to expect, and what setup is required before calling. Nothing critical appears missing for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 hitl_id, challenger_id, and suspicious_channel. The description adds no parameter-specific detail beyond what the schema provides, which is acceptable but not exceptional. Baseline 3 is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (create), a specific resource (Proof-Me cross-channel identity challenge), a clear type (CONFIRM), and the intended scenario (account holder approves/denies on a different channel than the suspicious contact used). This clearly distinguishes it from the many verification, HITL, and confirmation tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit post-call guidance: poll get_identity_challenge with the returned ID until terminal state. It also provides a clear access prerequisite and an explicit exclusion: start_login does NOT open this tool. It does not explicitly compare against alternative creation tools, but the context is clear enough for an agent to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the tool requires server-level API key configuration, that it returns the current state, and that browser login via start_login is insufficient. For a read-only getter, this is meaningful behavioral context beyond the basic 'get by ID' phrasing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, followed by a compact and relevant access note. Every sentence adds value, and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, full schema coverage, and lack of an output schema, the description sufficiently explains what is returned (status and usage statistics) and the access prerequisites. An agent has enough information to call the tool correctly and interpret its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, id, and the schema already describes it as 'Authorization ID' with 100% coverage. The description does not add additional parameter-level detail, which is acceptable because the schema fully documents the parameter. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get an authorization by ID' and clarifies the returned data is the current state including status and usage statistics. This is clearly distinct from sibling tools like list_authorizations, which would return multiple authorizations rather than one by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when the tool can be used by stating that a Proof account and PROOF_API_KEY are required. It also explicitly warns that start_login does NOT open this tool, which is an important exclusion that prevents a common misuse. It does not name sibling alternatives like list_authorizations, but the access guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals important access requirements: a Proof account, setting PROOF_API_KEY, restarting the server, and calling the tool again. It also clarifies a potential misunderstanding by stating start_login does not open this tool. This is meaningful behavioral context beyond the simple 'get' action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a clearly labeled access note. The access paragraph is necessary and not overly verbose, though it could be tightened slightly. Overall it earns its place without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description sufficiently explains what it returns ('all default message templates') and the required setup. It could mention the return format or list items, but the simplicity of the tool makes that a minor gap rather than a serious omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there are no parameter semantics to document. The baseline of 4 applies because the description does not need to elaborate on parameters, and it correctly focuses on purpose and access instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get all default message templates', which is a specific verb plus resource, and immediately clarifies these are 'built-in templates used when no custom template is set.' This distinguishes them from custom/managed templates among the many template-related sibling tools, even without naming a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when this tool is relevant: retrieving built-in default templates when no custom template is set. It also provides operational guidance about needing a Proof account, setting PROOF_API_KEY, restarting the server, and explicitly notes that start_login does not open this tool. It does not explicitly compare against list_templates or get_template, but the 'default vs custom' framing supplies enough context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals auth requirements, a restart requirement, a specific 'start_login does NOT open this tool' exclusion, and the exact returned key material. It does not discuss side effects, but the verb 'Get' makes the read-only nature clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one purpose sentence, one return-value sentence, and a short access note. Every sentence earns its place and the critical access caveat is separated for visibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with no output schema, this description is complete: it states what is returned, what is required before calling, and how authentication differs from the start_login flow. An agent has enough information to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with hitl_id already documented as 'HITL config ID', so the baseline is 3. The description adds no additional semantic detail about where the ID comes from or its format, but no compensation is needed given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb ('Get'), object ('encryption keypair'), and scope ('for a HITL config'), then enumerates the exact return fields. This clearly distinguishes get_hitl_keys from sibling key-management tools like upload_hitl_keys and delete_hitl_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access context: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted. It also warns that start_login does not open this tool. It does not explicitly name the alternative tools for uploading/deleting keys, so it misses the top tier for tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses authentication requirements, an operational prerequisite (restart after setting PROOF_API_KEY), and return behavior including aggregate status, winning_channel, per-channel statuses, and proof token expiry. It does not cover error or not-found behavior, but that is a minor gap for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the core status/return info comes first, followed by a distinct, actionable ACCESS note. Every sentence adds value, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only status tool with no output schema and no annotations, the description covers the essential context needed to call it correctly: what it returns, what values to expect, and how to authenticate. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains group_id's format (vg_<hex>). The description only says 'by its group_id' and adds no meaningful parameter semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get the status'), the exact resource ('multi-channel verification group'), and the lookup key ('group_id'). It also enumerates what is returned, which immediately distinguishes this from single-channel verification or proof-status tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete access guidance: a Proof account is required, PROOF_API_KEY must be set, the server must be restarted, and start_login does not enable this tool. It does not name sibling alternatives explicitly, but the read-status purpose and multi-channel scope make the intended usage reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the possible statuses, clarifies that a live proof reads 'active', and warns about authentication requirements. It does not describe behavior for unknown IDs or edge cases, but this is adequate for a simple status getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by the access warning in a separate paragraph. Every sentence contributes useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only-looking tool with no output schema, the description fully covers input format, return statuses, and authentication setup. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description merely repeats the schema's parameter description. It does not add new meaning beyond the structured field, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact operation (get status of a proof), the resource it applies to (public handle or verification ID), and the specific statuses returned. This clearly differentiates it from related siblings like validate_proof or revoke_proof, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisite guidance: the caller needs a Proof account, must set PROOF_API_KEY, and must restart the server. It also warns that start_login does not open this tool, which is a useful exclusion. It does not explicitly compare against other proof-related tools, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explicitly discloses an access requirement (Proof account, PROOF_API_KEY, server restart) and clarifies that start_login does not grant access. This is meaningful auth-related context, though it does not cover error behavior or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses only a few targeted sentences. The access block is compact and every sentence adds necessary operational context without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description is complete: it explains what the tool does, what the tokens are for, and the required setup. An agent can reasonably invoke it given the schema and this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single 'id' parameter as a Verification request ID. The description does not add extra meaning beyond that, which matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and a specific resource ('proof tokens for verified assets in a verification request'). It also clarifies that these tokens support offline verification, which distinguishes this tool from siblings like validate_proof or get_proof_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is relevant: when proof tokens from a verification request are needed for offline verification. It does not explicitly name alternative tools or state when not to use it, but the access note about start_login being insufficient is useful routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It reveals the non-obvious auth prerequisite and the limitation that start_login will not grant access. It does not explicitly state read-only behavior or error cases, but the access caveat is the most important behavioral trait here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states purpose and returned content, the second gives the necessary access action. The structure is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter with no output schema, this is complete: it describes what the tool returns, implies the id's role, and gives the auth setup required. Nothing needed to invoke it successfully is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single 'id' parameter with 100% coverage, so the baseline applies. The description adds little parameter-specific meaning beyond identifying the target as a delivery attempt.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get details of a single webhook delivery attempt' with concrete contents (request/response payloads, retry history). The 'single' qualifier distinguishes it from list_webhook_deliveries and other webhook sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear access context: requires a Proof account, PROOF_API_KEY, and a server restart before retrying. It also explicitly warns that start_login does not open this tool. It does not name list_webhook_deliveries as the likely precursor, so alternatives are not fully covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool lists only active sessions, scopes results to the current user, shows specific attributes, and behaves differently under API key authentication (no is_current flag). This is meaningful transparency for a read-only listing tool, though it does not discuss output shape or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the core purpose before adding caveats. The access instruction and the 'start_login does NOT open this tool' warning each add practical value, but the ACCESS block is slightly informal and could be tightened; nevertheless, no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with no output schema, the description is complete enough: it states what the tool lists, what details are shown, the access requirement, and the API-key-specific behavior. It does not fully specify return formats or pagination, but for this simple listing operation the provided context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description is not required to explain parameter behavior. The baseline for parameter-free tools is 4, and the description even adds relevant context about the API key authentication mode, which is more than necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('List all active authentication sessions') and the resource ('for the current user'). It also enumerates the returned session details (channel, user agent, expiry), making the tool's purpose unambiguous and distinct from related session tools like create_session or revoke_auth_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical context: it requires a Proof account and an API key, instructs the agent to set PROOF_API_KEY and restart the server, and explicitly warns that start_login does NOT open this tool. It does not explicitly name alternative tools or state when to prefer list_auth_sessions over get_session or revoke_auth_session, but the access prerequisite and the login-flow caveat provide solid usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses an important security behavior (identifiers are never returned, citing SEC-PM-006) and the authentication requirement. It stops short of describing error conditions or response shape, but covers the key behavioral traits for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action comes first, followed by the most important return limitation and the access prerequisite. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with two fully documented parameters, the description covers the essential context: what is returned, what is never returned, and how to enable access. The explicit return fields partially compensate for the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both required parameters (id and member_id) with descriptions and validation patterns, so schema coverage is 100%. The description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List a Circle member's channels') and the specific resource. It also adds the distinctive return-scope detail (channel metadata only, never an identifier), which helps differentiate it from sibling tools like list_circle_members or add_circle_member_channel.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access context: a Proof account is required, PROOF_API_KEY must be set, and start_login does not enable this tool. It provides a clear precondition and one exclusion, though it does not directly compare against other circle-related list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the behavioral disclosure burden. It explicitly warns that secrets are not returned and documents the authentication requirement, including the two access paths. It does not mention pagination or rate limits, but for a zero-parameter read-only list tool, the provided details are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core purpose before the access instructions. The ACCESS sentence is verbose but earns its place because it tells agents how to authenticate and recover from a session failure. No fluff or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list operation with no output schema, the description provides what an agent needs: what is listed, what is returned, and how to gain access. The main gap is that 'credential metadata' is not enumerated, but the tool's simplicity keeps this from being a major omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description adds relevant context about the result type and access requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('stored DNS provider credentials') and scope ('for the authenticated account'). It also clarifies the return type ('credential metadata (not secret values)'), which removes ambiguity and distinguishes it from credential creation/deletion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to enumerate DNS provider credentials for the current account. It also provides actionable access guidance—setting PROOF_API_KEY or using start_login to open a session. It does not explicitly contrast with siblings like get_dns_providers, but the purpose is clear enough that an agent can select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does address authentication: it requires a Proof account and explains the API key or start_login session path. It also signals that a session must be opened before the tool will work. It does not mention side-effect safety or result behavior, but 'List' and the scoping provide sufficient context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, and the access note is separated into a compact second block. No irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list operation, the description covers what it returns (verification requests), who they belong to (the authenticated user), and the auth prerequisite. No critical gap for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so there are no parameter semantics to clarify. Baseline for 0-param tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'List' and the scoped resource 'verification requests created by the authenticated user.' The authenticated-user qualifier distinguishes it from broader siblings like list_verification_requests and list_incoming_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage via the 'created by the authenticated user' scope, and the ACCESS note explains the prerequisite authentication state. However, it does not explicitly name alternatives or state when not to use it, so the usage guidance is mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses that the tool requires a Proof account and returns templates organized by channel and message type, but it does not state whether this operation has side effects, pagination limits, or any other behavioral details beyond the listing itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the main action and output shape come first, followed by a clearly labeled access note. Every sentence adds useful information and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema listing tool, the description covers the essential context: what is listed, the account scope, how results are organized, and the required setup to authenticate. The tool is simple enough that no additional information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there is nothing meaningful to add about parameters. The description's mention of result organization provides context, but parameter semantics are inherently fully covered by the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all custom message templates for the authenticated account, and specifies the result organization by channel and message type. This distinguishes it from related tools like get_default_templates, get_template, and list_profile_templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete access prerequisites: a Proof account, setting PROOF_API_KEY, restarting the server, and calling again. It also explicitly notes that start_login does not open this tool, preventing a common misuse. It does not explicitly compare to alternative template listing tools, but the 'custom' vs 'default' distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and does a solid job: it discloses the side effect of sending an OTP, states the return of a session ID, and surfaces the prerequisite that a Proof account and session or API key are needed. It does not describe every edge behavior, such as expiration or duplicate handling, but it covers the key observable behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the core purpose, the second covers side effects and return value, and the third provides necessary access context. Every sentence earns its place, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter initiation tool with no output schema, the description is complete: it explains what the tool does, what it sends, what it returns, and what access is needed. The hint to verify with the returned session ID contextualizes the next step without requiring an exhaustive sibling comparison.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes 'email' as an email-formatted string used to add an email address. The description adds a little extra context by noting the OTP is sent to that email, but this is not a major semantic expansion beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase, 'Start adding a new email address,' names the immediate action ('Sends an OTP code to the email'), and the outcome ('Returns a session ID to verify with'). This clearly distinguishes it from sibling tools like verify_email_otp, resend_email_otp, get_add_email_status, and remove_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to call this tool: initiating the addition of an email address that will be verified by OTP. It also includes important access guidance, noting that a Proof account is required and explaining how to authenticate via PROOF_API_KEY or start_login before calling. It does not explicitly name sibling alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals that the operation is limited to the display name, that identity binding is immutable after creation, and that a specific authentication setup (PROOF_API_KEY + server restart) is required. It does not describe response behavior or side effects beyond the mutation, but the key constraints are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary action, followed by a crucial mutability constraint and an access note. Every sentence adds distinct value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter update tool with no output schema, the description is sufficiently complete. It states the operation, the mutability boundary, the authentication prerequisite, and the setup action needed. An agent can select and invoke the tool correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The input schema already documents id as 'Circle ID' and name as 'New name for the Circle.' The description adds context that name is the only mutable field, but it does not add new parameter-level format or usage details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Update a Circle's name.' It further disambiguates from sibling tools by stating that only the display name is mutable and that profile/identity binding is create-only, making it clear this is not a general circle-editing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (rename a Circle) and explicitly excludes a key use case: changing profile/identity binding, which is create-only. It also provides access guidance by requiring a Proof account and API key, and warns that start_login does not open this tool. However, it does not explicitly name an alternative tool such as create_circle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and delivers thoroughly: it spells out the verification chain (signature → principal → delegate → revocation status, including the cascade to domain control proof), states that no API key is required, and explicitly bounds what a verified result means — authorization for scopes, NOT safety, audit, or endorsement. It also discloses edge-case behavior honestly (local/unpublished artifact → report the absence of a comparable identity rather than emit a mismatch).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose in the first sentence, and nearly every sentence earns its place given the subtle failure modes (copied tokens, self-declared identity, stale resolution). The trade-off is a dense unbroken wall of text with heavy ALL-CAPS emphasis; paragraph breaks would materially improve scannability for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with nested objects, no annotations, and no output schema, the input semantics, identity-resolution rules, and verdict semantics are thoroughly covered. The notable gaps are the absence of any description of the return shape (no output schema exists, so an agent cannot predict what a verdict looks like) and no differentiation from the plural sibling verify_delegations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema's per-parameter descriptions are already unusually rich (delegate: 'never a value read from inside the artifact... resolved afresh'; expected_principal: 'any domain owner can mint a valid delegation for someone else's package'). The description reinforces the attack model and why both pins are required together, but adds only marginal meaning beyond what the schema already states, so the high-coverage baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Verify a Proof of Delegation — the attestation that a domain authorized a specific agent artifact.' The clarifying definition of what a proof of delegation is distinguishes this from sibling tools like verify_domain, validate_proof, and get_proof_status without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides unusually detailed invocation guidance: pass either a card or a raw token PLUS two independently established pins, resolve the artifact identity afresh and never from inside the artifact, and report rather than return a mismatch when no independent identity exists. However, it never explicitly names alternative tools or exclusion conditions (e.g., when to use verify_delegations or validate_proof instead), so the routing to siblings remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it discloses the create side effect, the mandatory authorization follow-up, the Telegram chat_id discovery prerequisite, and the Proof account/API key restart requirement. It does not describe return values or duplicate/overwrite behavior, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then splits into Agent usage and ACCESS sections. Each sentence provides distinct, actionable information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with three parameters, nested channel variants, no output schema, and no annotations, the description covers the prerequisites, call sequencing, and channel-specific setup. It would be slightly more complete if it mentioned the expected response/ID and explicitly routed existing-config changes to update_hitl, but the agent can still invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by mapping 'channels' to approval destinations, 'timeout_seconds' to the default timeout, and by explaining that Telegram requires a chat_id obtained via create_chat_id_discovery. That workflow-level hint goes beyond what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a HITL config' and specifies it defines which messaging channels receive approval requests and the default timeout. It clearly distinguishes this from related workflow tools by stating it must be followed by request_hitl_authorization and that create_confirmation consumes it afterward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to call request_hitl_authorization after creation, before using create_confirmation, and to call create_chat_id_discovery first for Telegram channels. It also gives the PROOF_API_KEY prerequisite and notes that start_login does not open this tool. It does not explicitly tell the agent to use update_hitl for existing configs, which would be the natural 'when-not-to-use' complement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It explains that the first completed channel wins, losing siblings are canceled, a single proof token is yielded, quota is charged per channel, and the response structure includes group_id, channels, deep_link/sms_message, and qr_text. It also discloses the authentication prerequisite and the important fact that start_login does not open this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized: core behavior, agent-facing response handling, and access requirements are separated clearly. It front-loads the essential first-wins semantics and keeps the operational caveats together, though some phrasing could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and a multi-step verification flow, the description explains the response shape, how to present each channel to the user, how to interpret qr_text correctly, which status tool to poll, and what authentication setup is needed. Nothing essential to invoking and completing the flow is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies. The description reinforces channel behavior and mentions the response representation, but it does not add substantial parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 multi-channel phone verification') and immediately defines the OR/first-wins semantics that distinguish it from single-channel verification tools. It also references the related follow-up tool get_multi_channel_verification_status, helping the agent place this tool in the broader workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit agent workflow guidance: pass deep_link values to render_auth_link, present sms_message to the user, poll get_multi_channel_verification_status with the group_id, and do not use start_login to open this tool. It does not explicitly name a single-channel alternative such as create_verification as a when-not case, so usage guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden of behavioral disclosure. It discloses the 24-hour rate limit, the need for an authenticated Proof account, and the required setup step. It does not describe the output format or whether the export is synchronous, but the disclosed constraints are meaningful and actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three focused sentences: the purpose, the rate limit, and the access prerequisite. The most important information is front-loaded, and every sentence adds value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description covers scope, rate limiting, authentication, and a critical setup caveat. It is nearly complete, though it could briefly mention what the returned export looks like or that it returns the account data directly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so there is no parameter schema burden. The baseline for zero-parameter tools is 4, and the description adds no unnecessary parameter explanations, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states an exact verb and resource: it exports all account data, and frames it under GDPR Article 20 for data portability. This clearly distinguishes it from narrower export-like siblings such as export_authorizations, since it covers all account data rather than a subset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit prerequisites (Proof account, PROOF_API_KEY, server restart) and the rate limit of 1 export per 24 hours. It also explicitly warns that start_login does not enable this tool, which is a useful when-not signal, though it does not name an alternative tool for narrower exports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds meaningful access and setup behavior: required API key, need to restart the server, and the fact that the login flow does not unlock this tool. It does not describe the exact return format or error behavior, but for a simple read operation this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the core purpose, and the second clearly labels the access requirements with 'ACCESS:'. Every sentence adds practical information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool, the description covers the essential details: what it returns and the required setup. The main gap is not explicitly clarifying how this tool relates to generic asset tools like list_assets, and it does not describe the return structure, though no output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%, so there is no parameter documentation burden for the description. The baseline of 4 applies because no parameters exist and nothing additional is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Get') and resource ('available verified assets that can be displayed on the user's profile'), and further specifies the return value as assets 'eligible for public proof display.' This distinguishes it from broader sibling tools like list_assets or get_asset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit access prerequisites: a Proof account, setting PROOF_API_KEY, restarting the server, and then calling the tool again. It also warns that start_login does NOT open this tool, which is a useful exclusion. However, it does not explicitly contrast this tool with alternative asset-related tools such as list_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses the authentication requirement and the fact that start_login is insufficient, which are non-obvious behavioral constraints. The read-only nature is implied by 'Get' and the absence of stated side effects, though it does not explicitly guarantee no mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the core purpose appears in the first sentence, and the access caveat is a separate, clearly labeled note. Every sentence provides actionable information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter getter with no output schema, the description is nearly complete: it states the resource, the included fields, and the access requirements. It could be slightly stronger by explicitly mentioning the sibling update_settings or clarifying whether any other settings are excluded, but the agent has enough to call it successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds contextual meaning by listing what settings are returned, which helps the agent understand the tool's purpose even though no parameters need explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves account settings and enumerates specific included fields (business name, logo, colors, support email, email theme). This distinguishes it from sibling getter tools like get_current_user or get_usage, and from update_settings by using the verb 'Get.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access prerequisites: requires a Proof account, PROOF_API_KEY must be set, and the server restarted. It also warns that start_login does NOT open this tool, which prevents a common misuse. It does not explicitly name alternative getter tools or when to prefer them, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the behavioral disclosure burden. It discloses a key behavioral trait: the tool depends on server-level API key configuration, not on the interactive login flow. It also implies a read-only statistical operation. It could add response-shape details or rate-limit notes, but for a zero-parameter read tool the access behavior is the most critical missing context and it is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a necessary access prerequisite. Every sentence contributes: the first defines the operation, the second explains exactly how to enable it and warns against a likely wrong path (start_login).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter statistics tool with no output schema, the description gives enough information to call it successfully after configuration. It covers the required access setup and a high-level summary of the returned data. It could specify what 'recent activity' means or provide a sample return structure, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the baseline is 4. There are no parameter semantics to add; the description's mention of what statistics are returned partially substitutes for parameter-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get webhook delivery statistics') and enumerates the exact contents: total deliveries, success/failure counts, and recent activity. This distinguishes it from sibling tools like get_webhook_delivery and list_webhook_deliveries, which concern individual deliveries rather than aggregate statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when the tool can be used: a Proof account must exist, PROOF_API_KEY must be set, and the server must be restarted before calling. It also explicitly warns that start_login does not unlock this tool, which is a useful exclusion. It does not, however, name alternative tools or state when aggregate stats are preferable to listing deliveries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains the authentication prerequisite, the need to set PROOF_API_KEY and restart, and the notable trap that start_login does not unlock this tool. It could add more about the exact response shape, but the key behavioral context is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by the essential access caveat. Every sentence adds value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list operation, the description covers the essential context: what it lists, the account scope, and the required setup. Since there is no output schema, a bit more detail about the returned profile structure could help, but the description is largely sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add beyond the schema. This matches the baseline for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all profiles') and the resource scope ('for the authenticated account'), and explicitly clarifies that it returns all profiles including primary and secondary. This distinguishes it from single-profile tools like get_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear access guidance: a Proof account is required, PROOF_API_KEY must be set, and the server must be restarted before retrying. It also explicitly says start_login does NOT open this tool, which prevents misuse, though it does not name an alternative for fetching a single profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states destructive side effects: it deletes the member's channels and revokes live authorizations that routed through them. This is far more transparent than a generic 'remove member' statement and appropriately warns about irreversible consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main behavior and side effects are front-loaded in the first sentence. The access note is separated and concise. Every sentence earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive two-parameter operation with no output schema, the description is nearly complete: it explains the action, the side effects, the access requirement, and a common pitfall. It could go slightly further by stating whether removal is permanent or describing the response, but the essential context for invoking the tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'member_id' already documented in the schema. The description does not add parameter-level meaning beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Remove a member from a Circle.' It then details the two key consequences (deletes the member's channels and revokes live authorizations), which clearly distinguishes it from sibling tools like remove_circle_member_channel or delete_circle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear practical usage context: it requires a Proof account, the PROOF_API_KEY environment variable, and a server restart. It also explicitly warns that start_login does NOT open this tool, which is a helpful when-not signal. However, it does not mention alternatives or when to prefer a different circle member tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so well. It discloses idempotence, mirroring into the proof registry/CRL/status list, preservation of domain control proof and sibling delegations, different repeat behavior compared to proofs, and derived result fields. This is rich, accurate behavioral disclosure with no annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, and the three paragraphs carry substantive information about effects, idempotency, result fields, and access. It is dense but not bloated; the access paragraph could be tightened slightly, but every sentence contributes useful guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, yet the description supplies the critical invocation context: authentication prerequisite, propagation of the revocation, idempotency semantics, and the derived effective_status/is_valid fields. An agent has enough information to select and invoke the tool correctly without guessing at side effects or access requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters fully (100% description coverage), so the baseline is 3. The description reinforces that id targets one delegation and highlights the ph_dlg_ handle path, but it does not add significant field-level semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening phrase 'Revoke ONE delegation' names a specific verb and resource, explicitly limits scope, and distinguishes this from proof revocation ('unlike a PROOF'). The description also ties into the delegation/proof domain clearly, so an agent can tell it apart from revoke_proof and other revoke_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit access context: 'needs a Proof account,' 'Set PROOF_API_KEY and restart this server,' and 'start_login does NOT open this tool.' It also relates the tool to revoke_proof via the ph_dlg_ handle. It does not, however, state a crisp condition for choosing this tool over revoke_proof in all cases, so it stops short of full alternative-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden and does so well: it discloses prefix anchoring, case sensitivity, restriction to indexed plaintext fields, recipient identifier masking, account scoping, and the PROOF_API_KEY prerequisite. It does not describe result grouping, pagination, or error behavior, but the key operational traits are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: purpose and key constraints come first, followed by a clearly separated access prerequisite. Every sentence contributes meaningful information, and there is no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema or annotations, the description covers invocation-critical context: account scoping, access requirements, matching behavior, and identifier masking. It doesn't specify the return shape or how results are grouped across buckets, but it is sufficient for an agent to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying how 'q' behaves beyond the schema: case-sensitive prefix matching over indexed plaintext fields only, with masked recipient identifiers. It also reinforces the meaning of the six 'type' buckets. Limit and environment semantics remain adequately described by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly names the operation ('Prefix-anchored global account search') and the exact resource scope: six named buckets. It also adds distinguishing constraints like case-sensitive matching, masked recipient identifiers, and account scoping, which clearly separates it from the many resource-specific get/list siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'global account search across six resource buckets' signals that this tool is for cross-bucket lookup, while the schema's 'type' parameter describes narrowing to a single bucket. The access note and the explicit 'start_login does NOT open this tool' provide important operational guidance, though it doesn't name specific alternative tools or say 'use this instead of X'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and it delivers: it discloses the backoff algorithm ('2s initial, 1.5x, 30s max with jitter'), semantics of each terminal state, the pending/timeout retry behavior ('a longer wait is cut off by the client while the server is still polling'), and the auth prerequisite (PROOF_API_KEY, server restart, start_login does not open the tool). This is precisely the non-obvious context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place: backoff parameters, terminal-state semantics, the orchestration flow, the auth blocker, and the start_login exclusion. The labeled sections ('Agent usage:', 'ACCESS:') make it scannable, and the core behavior is front-loaded in the opening sentence. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers almost everything an agent needs to call it correctly: the triggering workflow, retry loop, terminal states, downstream use of the discovered chat_id, and access requirements. The one notable gap is that the response shape for 'completed' is not described beyond the terminal state name — an agent doesn't know the exact field name holding the chat_id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The schema already documents token provenance ('Discovery token from create_chat_id_discovery') and the timeout_seconds behavior in detail, including the default, max, and client-timeout caveat. The description adds marginal cross-references ('poll with the returned token') but does not materially extend what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource: 'Poll a chat ID discovery token until the user interacts with the Telegram bot.' This clearly distinguishes it from siblings like create_chat_id_discovery (token creation), poll_chat_id_discovery (single poll), and render_auth_link (link rendering). The terminal states ('completed', 'expired', 'pending') further pin down what the tool accomplishes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Agent usage' paragraph gives an explicit workflow: call after create_chat_id_discovery, present the deep_link via render_auth_link first, then poll with the returned token. It also provides an explicit exclusion: 'start_login does NOT open this tool.' It falls short of a 5 only because it never contrasts with the closest sibling, poll_chat_id_discovery, to explain when the blocking wait variant is preferred over a one-shot poll.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full responsibility and does so well: it discloses that the operation is a soft delete, changes status to 'archived', removes the Circle from the default list, and remains recoverable. It also explains the API-key access requirement, preventing the agent from assuming permanent deletion or expecting start_login to work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: primary behavior first, recoverability second, access prerequisite last. Every sentence contributes actionable information, with no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation tool with no output schema, this is complete: it explains what the operation does, its side effects, reversibility, and the required setup. An agent has enough information to decide when to call it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single required parameter with a description ('Circle ID to archive') at 100% coverage. The tool description adds no extra parameter-level detail beyond restating that the Circle is archived, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb, resource, and effect: 'Archive a Circle (soft delete — sets status to archived)'. It also distinguishes this from a true delete by explicitly noting recoverability, which is especially helpful given the tool is named delete_circle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use: archiving a Circle and how to later recover it via list_circles with status='archived'. It also provides a necessary access prerequisite and warns that start_login does not authorize this tool. It does not explicitly name an alternative tool for hard deletion, but none appears among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the destructive consequence of permanently unreadable ciphertexts, the authentication prerequisite, and the required configuration step. This is strong behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: operation, irreversible consequence, then access prerequisite. The warning is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool, it covers the resource affected, the permanent consequence, the authentication model, and the required setup action. The absence of an output schema is acceptable because the operation's success/failure is self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter hitl_id is fully described in the schema as 'HITL config ID', and schema coverage is 100%. The description adds no parameter-specific detail, which matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific operation and resource: deleting the encryption keypair from a HITL config. The warning about permanent unreadability clarifies the consequence, and the wording distinguishes this from delete_hitl, which deletes the config itself rather than its keypair.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: a Proof account is required, PROOF_API_KEY must be set, the server restarted, and start_login will not authenticate this operation. It gives an explicit exclusion, though it does not name alternative tools for related key operations, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that the link expiry inherits the confirmation timeout, that only pending confirmations work, and that start_login does not open this tool. It also alerts the caller to the required environment setup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight paragraphs with no filler. The purpose is front-loaded in the first sentence, and the access note is separate and actionable, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, this description covers the essential context: what the tool returns (an approval link), when it works, how expiry behaves, and what access setup is required. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single id parameter as a 24-hex 'Confirmation ID' with 100% coverage. The description adds context ('pending confirmation', 'confirmation timeout') but does not materially expand the meaning of the id parameter, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Generate a fresh approval link for a pending confirmation.' This clearly sets it apart from sibling tools like get_confirmation or render_auth_link, and the 'Only works for pending confirmations' line adds scope rather than ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear conditions for use: it only works for pending confirmations, and it explains the access prerequisite (Proof account, PROOF_API_KEY, server restart). It does not explicitly name alternative tools or state 'use X instead,' so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It communicates read-only intent ('Get metadata') and discloses access requirements and the authentication prerequisite. The note about a session opening the tool after start_login adds useful operational behavior beyond the bare function name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then adds essential access instructions in a separate clearly marked section. Every sentence earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is complete: it states what metadata is returned, names the included components, and gives the necessary authentication steps. An agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with 100% coverage, so there are no parameters that need explanation. The description also mentions returned credential fields, which indirectly informs what the tool provides even though it does not need to document parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a specific resource ('metadata for all supported DNS providers'), and clarifies exactly what is returned: credential fields and documentation links. This clearly distinguishes it from siblings like connect_dns_provider or list_dns_credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear prerequisite context: a Proof account is needed, and it explains two ways to authenticate (set PROOF_API_KEY or sign in via start_login). It does not explicitly compare against alternative tools, but for a zero-parameter metadata list, the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully states that the return value is a signed list of all revoked proof IDs and that it is cacheable for 5 minutes, and the verb 'Get' implies a non-mutating read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The purpose is stated first, followed by the return content and caching behavior, making it efficiently scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description is complete: it states what is returned, the signed nature of the list, and the caching window. There is no output schema, so the description's return-value disclosure is essential and present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already documents this with an empty properties object. The description adds no parameter-specific meaning, but with no parameters to document, the baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('revocation list'), and immediately clarifies its purpose with 'for offline proof validation'. This distinguishes it from related sibling tools like revoke_proof and validate_proof, making the tool's role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for offline proof validation' provides clear context on when this tool should be used. However, it does not explicitly name alternative tools or state when not to use it, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral weight and does so thoroughly: old key stops working immediately, new secret is returned only once, secret is visible in AI conversation context, requires 2FA, and requires a Proof account/auth setup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: the core effect is front-loaded, followed by critical security/visibility implications, then precise agent-facing 2FA steps, then access requirements. The numbered workflow makes the required sequence easy to follow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a sensitive one-parameter operation: it explains the outcome, the irreversible consequence, the 2FA prerequisite, the execution order, and the access/auth condition. No output schema exists, but the key return information is explicitly disclosed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the single 'id' parameter is already documented adequately. The description adds slight context by noting the ID remains the same after regeneration, but no substantial parameter detail is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Regenerate') with a clear resource ('API key') and distinguishes the action from create/revoke by explaining it keeps the same ID and settings while issuing a new secret. It also states the key consequence ('old key stops working immediately'), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the precondition (2FA) and provides an ordered workflow for when to call this tool versus the 2FA helper tools. It doesn't explicitly name sibling alternatives like create_api_key or revoke_api_key, but the regenerate semantics imply the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the key immediately stops working, that revocation cannot be undone, that 2FA must precede the call, and that a Proof account is required. This is strong behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence delivers the core purpose immediately. The structured Agent usage and ACCESS sections are detailed but every sentence adds necessary operational information for a destructive, 2FA-gated action. Nothing feels redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers the essential context completely: what it does, the irreversible consequence, the mandatory 2FA sequence, and account access requirements. An agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes the id parameter as the 'API key ID to revoke.' The description says 'by ID' but adds no meaningful semantic detail beyond what the schema provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Revoke an API key by ID,' and immediately clarifies the irreversible consequence. This clearly distinguishes it from sibling tools like revoke_proof, revoke_asset, revoke_auth_session, and revoke_authorization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives excellent operational context: a 2FA prerequisite with an explicit step-by-step flow, plus access requirements. It does not explicitly name alternatives such as regenerate_api_key, but the destructive nature and unique scope make the appropriate use case unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses side effects (sends a code), conditional return values (deep_link, qr_code, qr_text, session_id), the email requires_email_selection case where no session is created, and that email may deliver a magic link instead of a code. It also states the access prerequisite clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with a front-loaded purpose and a numbered flow. Some channel instructions are repeated in different forms, which adds a little redundancy, but the complexity of the 2FA flow justifies most of the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values and edge cases itself. It covers session_id, channel-specific artifacts, email selection, SMS flow, the no-session case, magic-link handling, polling, and access setup. An agent has enough context to invoke the tool correctly in real scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful conditional semantics: when email_id is needed, how channel changes the response and user action, and how action_type fits into the flow. It does not detail every action_type value, but the schema already enumerates and describes them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool starts a 2FA challenge, sends a verification code, and returns a session ID plus channel-specific artifacts. However, it never distinguishes itself from the near-named sibling start_2fa_for_action, so an agent could be uncertain which of the two starting tools to choose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a full, numbered agent workflow: when to call the tool, how to handle each channel, when to re-call with email_id, when to poll get_2fa_status, and what to do on verified or expired outcomes. It also gives explicit prohibitions, such as not announcing unsent messages and never handing qr_text to a link renderer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the 400 unsupported_for_type error, the out-of-band delivery requirement, the PROOF_API_KEY access prerequisite, and restart guidance. It does not describe what a successful submission returns or whether the verification is completed synchronously, but it is unusually transparent for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, acceptance constraints, alternatives, and access requirements. The most important routing information is front-loaded, and the access note is cleanly separated at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema and no annotations, this description is remarkably complete. It tells the agent exactly which verification types/channels are valid, what happens for invalid pairs, which sibling to use instead, and what setup is required. Nothing essential to invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents id and code. The description adds contextual value by clarifying that the code must have been delivered out-of-band and that the id refers to a pending verification, but it does not significantly expand on the parameters' format or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Submit an OTP/challenge code for a pending verification.' It then sharply scopes the accepted cases ('type email' and 'type domain with channel email'), which distinguishes it from siblings like trigger_verification and verify_email_otp without needing to inspect schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool is accepted and when it is not. It names trigger_verification as the alternative for domain-over-dns/http/auto, explains how phone, social, and telegram_bot verifications complete elsewhere, and even warns that start_login does not open this tool. This leaves little ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses exponential backoff with parameters, jitter, terminal-state conditions, timeout returning status 'pending', and the auth requirement. There is no contradiction with structured data since annotations are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the core polling behavior, then tucks access/recovery guidance into a clearly labeled block. Every sentence provides actionable information with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with no output schema, the description covers the key operational facts: terminal states, retry semantics, timeout behavior, and access setup. An agent has enough to invoke it correctly and know what to expect on timeout. The only omission is the exact success response shape, which is not required absent an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 schema already documents id and timeout_seconds thoroughly, including default/max and client-timeout warning; the description adds polling backoff behavior but not new parameter-specific meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Poll') and resource ('a verification request') and defines the goal as reaching a terminal state with explicit states listed. This clearly separates it from get/list tools by signaling blocking behavior, despite not naming a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete operative guidance: when a verification request needs to be awaited, poll until completed/expired/cancelled, and on timeout call again with the same identifier. It also warns about prerequisites (Proof account and PROOF_API_KEY) and that start_login does not enable this tool. It does not explicitly compare against sibling polling tools, but that isn't needed because the resource scope is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does it well. It discloses exponential backoff parameters, jitter, terminal-state semantics, the special meaning of cancelled/revoked, timeout behavior, and the need for a Proof account. This is unusually transparent for a polling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, backoff behavior, terminal-state nuance, timeout retry guidance, and access setup. It is front-loaded with the core action and avoids fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the terminal states, what happens on timeout, the wait-and-retry model, and the access requirement. For a tool whose main complexity is polling semantics and auth, this is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters at 100%, including the default, min/max, and client-timeout warning for timeout_seconds. The description adds useful polling context but no additional per-parameter meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Poll a verification until it reaches a terminal state,' and enumerates the exact terminal states. This clearly distinguishes it from sibling tools like get_verification, wait_for_login, or wait_for_request by identifying the resource and the polling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you must wait for a verification to reach a final state, and call it again on timeout with the same identifier. It also gives access prerequisites and warns that start_login does not unlock this tool. It does not explicitly name alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It reveals that the endpoint is public, that it creates a user or logs one in, that the response is intentionally uniform to avoid user enumeration, that email sends nothing, that sms responses contain no destination number, and that verification sets JWT and refresh cookies. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although lengthy, the description is dense, well-structured, and front-loaded with the core purpose before the workflow. Every paragraph and numbered step earns its place given the channel-specific caveats, and the warnings are concrete rather than generic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description takes on the burden of explaining return fields and follow-up expectations. It covers session id, deep_link, qr_code, qr_text, sms_message, email_sent, send_required, and the verification handoff. It also covers edge cases like sms lacking a destination number and the danger of treating qr_text as a link. This is complete for an onboarding tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful channel-specific semantics: email requires confirmation and a follow-up call, sms requires a phone number with no destination in the response, and telegram/whatsapp use deep_link for rendering. It does not fully enumerate parameter formats beyond the schema, but it substantially augments the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific verb and resource ('Create an account-bootstrap session for agent-driven onboarding') and adds the public-endpoint qualifier. It is clear, but it does not explicitly differentiate itself from closely related siblings like create_session, start_login, or create_verification, so an agent must infer the distinction from context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit numbered agent workflow, including when to call send_account_email versus relying on deep_link, when to use render_auth_link, and when to call wait_for_account_creation. It also states the condition for calling get_current_user to distinguish new vs. returning users, and warns against using sms deep_link or handing qr_text to a link renderer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the transparency burden. It discloses that member-declared channels are stored for later enrollment, that a Proof account is required, and that start_login does not open this tool. It could go further on side effects like whether creation is idempotent or what happens if a member seed fails, but the provided behavioral context is already quite strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: first the purpose, then an actionable agent workflow, then required access setup. Every sentence earns its place, including the non-obvious start_login exclusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the essential invocation context: what the tool creates, how to use it in sequence with sibling tools, and the API-key prerequisite. It does not describe the return value or potential partial-failure behavior, but the described workflow and prerequisites are sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining that members are optionally seeded and that their declared channels are stored for later enrollment invitations. This clarifies the intended role of the members parameter in the overall workflow, going beyond parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 Circle — a named group of trusted contacts.' It names the underlying people-primitive concept and clearly distinguishes this creation tool from sibling tools like update_circle, delete_circle, and add_circle_member.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit agent usage guidance: create the Circle, add members via add_circle_member or seed them here, then invite_circle_member to mint the enrollment deep link. It also documents the required access setup and explicitly states that start_login does NOT open this tool, preventing a common misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description fully carries the behavioral burden. It discloses that consent requests are delivered with no link to show, explains the meaning of 'pending' vs 'active', warns that an empty array means no recipients were resolved, and flags that the returned message can be misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well structured, front-loading the purpose and then covering process, return semantics, and edge cases. Slight redundancy around the approval prerequisite and the message warning costs it a perfect score, but every paragraph earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return shape, status semantics, failure mode, and next steps. It even covers access prerequisites and explicitly notes that start_login does not unlock this tool, making it actionable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'id' parameter is already documented as the HITL config ID. The description mentions the config and its channels but adds no additional parameter-level detail, so it meets the schema-driven baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Request authorization for a HITL config') and the mechanism ('Sends consent requests to all configured channels'), and ties it to a sibling by saying it must happen before create_confirmation works. This clearly distinguishes the tool from confirmation, authorization, and HITL management siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says this must be completed before create_confirmation will work, giving a concrete when-to-use rule. It also tells the agent to proceed only after the user confirms approval and warns about the empty-array branch where waiting would hang.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It thoroughly discloses irreversible action, global invalidation across status endpoint, public validator, revocation list, and Token Status List, and that only the proof is revoked. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: action, accepted identifiers, consequences, irreversibility, scope limitation, and access prerequisites. The core action is front-loaded, and the access note is clearly separated. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, what inputs are accepted, what the effects are, and what prerequisites are needed. With no output schema, the only missing element is a description of the response format or error behavior beyond the access error, which is a minor gap for a revocation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful detail about the 'id' parameter, explaining accepted formats (ph_ctl_* / ph_dlg_*) and linking to get_proof_status. The 'reason' parameter is thin, but the schema already says 'Reason for revocation', so no critical gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Revoke') and resource ('proof') and precisely defines the inputs by public handle or verification ID. It clearly differentiates from siblings by stating it revokes only the proof, not the underlying asset, consent, or delegation, so agents can distinguish it from revoke_asset and revoke_delegation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: the same addresses get_proof_status takes, and access requires a Proof account with PROOF_API_KEY plus a server restart. It explicitly says start_login does NOT open this tool, and clarifies the proof-only scope. However, it does not explicitly name revoke_asset or revoke_delegation as alternatives when the underlying object should be revoked, though the implication is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses server-side validation, key ID computation, client-side encryption of the private key, and that the server never sees the password. However, it does not state what happens if a key already exists or whether the operation overwrites or rejects, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well structured. The main purpose is front-loaded, the encryption note adds essential context, and the ACCESS block is a distinct, actionable set of instructions. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 required parameters, no annotations, and no output schema, the description covers the key operational requirements: what is uploaded, how it is validated, what the server computes, and what access setup is needed. The main gap is the lack of any statement about calling the tool repeatedly or whether an existing keypair is replaced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially that encrypted_private_key is already encrypted client-side and that the public key is validated as RSA-4096. It does not describe hitl_id or kdf_salt further, but the schema already documents those adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Upload an encryption keypair') and a clear resource ('for a HITL config'). It also adds validation detail (RSA-4096 public key, computed key ID) and is clearly distinguishable from sibling tools like get_hitl_keys and delete_hitl_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit access prerequisites: needs a Proof account, requires PROOF_API_KEY to be set, and instructs to restart the server before retrying. It also explicitly warns that start_login does NOT open this tool, preventing a wrong invocation path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals exponential backoff with jitter, terminal states, the absence of a returned link, timeout behavior, and access requirements. It even warns that a long wait can outlive an approval link while status is still pending.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but each section earns its place: polling behavior, agent usage, terminal states, link caveat, and access requirements. It is front-loaded with the core purpose and then provides necessary operational detail, though it is slightly denser than strictly required.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with no output schema and no annotations, the description is remarkably complete. It explains how to invoke it, what states to expect, what to do on timeout, how to get an approval link if needed, and what access setup is required. An agent has enough context to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented. The description adds useful usage context like 'Call this after create_confirmation with the returned confirmation ID,' but it does not meaningfully extend the parameter semantics beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Poll a confirmation until the approver responds.' It also distinguishes this tool from related siblings like get_confirmation and get_confirmation_approval_link by framing it as a polling operation with terminal states and no returned link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call this after create_confirmation with the returned confirmation ID, names get_confirmation_approval_link as the alternative when a link is needed, and notes that start_login does NOT open this tool. This is direct when/when-not/alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden, and it does so thoroughly. It states the attestation's limited meaning, the billable nature of each mint, the reject-never-truncate lifetime behavior, and the consistent result shape across list, get, and create. This lets an agent predict side effects and failure modes far better than the schema alone would.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: core action, scope limitation, billing impact, lifetime behavior, output shape, and access requirement. It is front-loaded with the primary purpose, and the ACCESS section is clearly separated for actionable setup information. There is no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is unusually complete. It states the output contents (publishable token plus effective_status/is_valid), the access path, the billing consequence, the lifetime constraint, and the attestation semantics. Combined with the fully described schema, an agent has enough information to call this tool correctly and anticipate its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it frames control_proof as a 'control-proven domain', explains the artifact types, and clarifies that over-long lifetimes are rejected rather than silently truncated. It does not repeat every parameter detail, but it adds contextual value where the schema is merely descriptive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Create a delegation (Proof of Delegation)') and clearly defines what the tool does: authorizing a typed url/purl artifact for capability scopes and producing a publishable signed token. It also differentiates the result from the list and get tools and explicitly contrasts access with start_login, so an agent can distinguish it from nearby tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear access prerequisites ('needs a Proof account', set PROOF_API_KEY, restart the server, then call again) and a clear when-not ('start_login does NOT open this tool'). It also flags that each mint is billable, which is an important usage consideration. It stops short of explicitly enumerating alternative delegation tools like verify_delegation or revoke_delegation, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and does so well. It discloses return payload semantics, the hosted callback flow, the PROOF_API_KEY access requirement, and the special handling of qr_text. It even names the terminal states (verified, failed, expired) that downstream polling will encounter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the tool's purpose and outputs, then moves into actionable agent usage, then access requirements. Every sentence adds operational value — the qr_text warning, the render_auth_link handoff, and the wait_for_session polling step are all necessary for correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters, a nested metadata object, no output schema, and no annotations, the description is remarkably complete. It covers what the tool returns, how the returned values should be used, what to avoid, how to poll for completion, and the access setup required. An agent can call this tool correctly with minimal inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 six parameters and their formats. The description does not add parameter-level detail beyond the schema, but it references the overall phone verification purpose and the output-driven workflow. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 phone verification session' — and immediately states the concrete return values (deep_link, qr_code, qr_text). It also distinguishes itself from the large sibling set by describing the hosted verification flow and explicitly noting that start_login does NOT open this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit downstream usage: pass deep_link to render_auth_link, never pass qr_text to a link renderer, print qr_text verbatim only for a real terminal, and poll with wait_for_session. It also provides a clear exclusion ('start_login does NOT open this tool') and an access prerequisite, making when and how to use the tool unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers: backoff algorithm details ('exponential backoff (2s initial, 1.5x, 30s max) with jitter'), terminal states, the 'pending' status on timeout, an ACCESS prerequisite (PROOF_API_KEY, server restart), and a negative behavioral note (start_login does not open it). This is comprehensive behavioral disclosure far beyond what any annotation would have provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place, covering purpose, backoff, workflow, terminal-state handling, challenge presentation, and access. It is clearly organized into labeled sections ('Agent usage:', 'ACCESS:') and front-loaded with the core purpose and backoff policy in the first sentence. The density is justified by the actionable operational detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers all return semantics via terminal states ('verified', 'expired') and the schema covers the 'pending' timeout case. The agent knows the prerequisites, the call sequence, how to render the challenge, and what to do on each outcome. For a two-parameter polling tool, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are already well-documented in the schema, including the timeout_seconds default, max, and timeout edge-case behavior. The description reinforces that session_id comes from start_2fa's return, matching the schema's '2FA session ID from start_2fa.' It adds workflow context but no new semantic information beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence, 'Poll a 2FA session until the user completes the challenge,' uses a specific verb (poll) and resource (2FA session) with a clear goal. It differentiates from siblings like get_2fa_status (a one-shot status check) and verify_2fa (a submission action), and explicitly declares what it is not: 'start_login does NOT open this tool.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit workflow: 'Call this after start_2fa with the returned session_id.' It specifies what to do on each terminal state ('verified' → proceed with the protected operation, 'expired' → offer to restart with start_2fa) and how to present the challenge (render_auth_link for deep_link, show sms_message for sms). It even names the alternative that does NOT open this tool, leaving no ambiguity about sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses exponential backoff with jitter, terminal states, the connection-scoped session behavior, the user_id field in the terminal body, and the equivalence of new-user vs existing-user flows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value: core behavior, retry policy, lifecycle semantics, and usage context are all covered without unnecessary filler. The 'Agent usage' section front-loads the most actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description gives an agent everything needed to call and interpret the tool correctly: how to start, what terminal states mean, what the user_id field indicates, and how to handle a pending timeout. It is complete for a polling tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already have solid descriptions. The tool description adds operational context by saying the id comes from create_account and that a pending result should be retried with the same id, which slightly exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource — 'Poll an account-bootstrap session' — and clearly ties it to 'after create_account with the returned session id.' This distinguishes it from the many sibling wait_* tools by identifying the exact flow it serves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Call this after create_account with the returned session id' and explains what to do on a 'pending' result. It does not explicitly state when not to use it or name alternatives like wait_for_login or wait_for_session, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers: exponential backoff parameters, terminal states, timeout semantics, retry guidance, and the side effect that a verified login keeps the session and signs account records. This is unusually transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then organizes agent guidance, terminal states, and retry behavior into compact, purposeful sentences. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema or annotations, this description tells an agent everything needed: when to call it, what statuses to expect, what each outcome means, and what to do on timeout. The side-effect explanation for 'verified' is especially valuable for a session-related tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining timeout_seconds' default, maximum, client-timeout interaction, and pending retry behavior, while also reinforcing that id comes from start_login.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Poll a login session until the user completes authentication.' It clearly distinguishes this from sibling wait_* tools by focusing on login sessions and explicitly tying it to start_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs agents to call this after start_login with the returned session ID, and it explains the pending-status retry behavior. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden — and it delivers extensively: no cross-item state, no persistence, independence of results, no API key required, per-item checked_at timestamps, and a full outcome taxonomy (confirmed_valid, confirmed_invalid, no_claim_found, unconfirmed) complete with the critical warning to never treat unconfirmed as a bad verdict. This is far beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long (~230 words) but every segment earns its place given the tool's complexity: four outcome semantics, a trust-boundary caveat, a timing subtlety, and an independence guarantee all need stating. The core purpose is front-loaded, and the density is purposeful rather than padded, though a few clauses could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is exceptionally complete: it covers the 50-item limit, the outcome vocabulary that substitutes for an output schema, per-item timing, authentication requirements, the trust boundary, and what the tool explicitly does NOT do. An agent has everything needed to decide when to call it and how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 schema already documents the items array and its nested requirements thoroughly. The description adds genuine value on top: the 'card XOR token' relationship, the identity rule (delegate must be resolved afresh, never read from inside the artifact), and the batch-shape parallel to verify_delegation. It reinforces rather than repeats the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object pair ('Batch-verify up to 50 Proof of Delegation artifacts in one call') and immediately names the sibling it complements ('instead of one verify_delegation call per artifact'), making the tool's scope and identity unmistakable. The 'inventory half of the checker' framing sharpens the distinction from its namesake.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance appears throughout: use it to re-check material you already trust en masse, not for discovery ('does NOT discover what you have installed and does NOT fetch anything on your behalf'). It names the alternative (verify_delegation) and the selection condition (batch vs single), and clarifies behavioral constraints like items being verified independently and revocation always being checked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It clearly warns that the secret is returned only once, will be visible in AI conversation context, requires 2FA session elevation, and that a 403 means the 2FA session expired. It also discloses the Proof account access requirement. This is thorough and highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: one-time secret warning, conversation visibility warning, profile binding effect, the 2FA sequence, the expiry recovery path, and access setup. It is front-loaded with the most critical information and uses clear numbered steps and labeled sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is remarkably complete: it explains the key security behavior of the response, the prerequisite 2FA flow, failure handling, and access requirements. The only thing not detailed is the full response shape, but the critical 'secret returned only once' fact is prominently conveyed, which is what an agent most needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 name, scopes, profile_id, and environment. The description adds meaningful extra semantics for profile_id by explaining that outbound messages will be branded as that project, which goes beyond the schema's binding/immutability note. This lifts it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Create a new API key.' It is immediately distinguishable from sibling tools like list_api_keys, revoke_api_key, and regenerate_api_key, and it emphasizes the unique one-time secret return. No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance including a mandatory 2FA prerequisite flow with numbered steps, references to start_2fa and get_2fa_status, and instructions for handling a 403 expiry. It also explains the access requirements for Proof accounts and the alternative start_login path. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden and meets it: it reveals creation semantics, return payload contents, the Telegram-open flow, auth requirements (Proof account / PROOF_API_KEY), and the dependency on subsequent polling. It also warns about qr_text renderer misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is longer than average, every sentence earns its place by carrying workflow, safety, or access-critical detail. The key facts are front-loaded, and the structure follows a clear progression: purpose, agent usage, and access.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is complete: it defines return values in usable formats, names successor tools (render_auth_link, poll_chat_id_discovery), and covers the access failure mode. An agent has enough information to call it and orchestrate the full chat ID discovery flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is complete, so no parameter-level explanation is needed. The description adds no parameter meaning, but with no parameters to document, the baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource statement, 'Create a Telegram chat ID discovery token,' and enumerates concrete return artifacts (deep_link, qr_code, qr_text). This clearly distinguishes the tool from polling, rendering, and login-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit workflow instructions: pass deep_link to render_auth_link, never hand qr_text to a link renderer, print qr_text only in a real terminal, poll with the returned token, and use the discovered chat_id for HITL config. It also states access prerequisites and warns that start_login does not open this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full behavioral burden. It thoroughly discloses branch behavior: LIVE vs pk_test_ telegram_bot behavior, challenge presence, no qr_text, deep_link on messenger channels, OTP code flow, and the Proof API key prerequisite. This goes well beyond a simple 'create' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but information-rich, with the core purpose front-loaded and all major behavioral branches covered. It is somewhat long and would benefit from bullet structure, but every sentence contributes meaningful usage or behavior context rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 9 parameters, no output schema, and no annotations, the description is unusually complete: it explains response shape, channel-specific flows, tracking next steps, rendering links, and the API key access prerequisite. An agent has enough context to call it correctly and follow up appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 substantial meaning beyond the schema: concrete type/channel/identifier examples, the interaction between telegram_bot and test keys, what challenge objects convey, and which response fields are absent. This materially improves parameter selection and interpretation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 identity verification' and immediately clarifies it initiates a verification flow for an asset identifier. It provides concrete example inputs and explicitly routes deep-link handling to render_auth_link, distinguishing its role from that sibling and from start_login.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit agent-facing usage guidance: pass type, channel, and identifier, with concrete examples. It also states when to use alternatives — pass deep_link to render_auth_link, poll get_verification or use wait_for_verification for OTP flows — and warns that start_login does NOT open this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility, and it delivers: it discloses that the response is redacted, that the key hash and full secret are never returned, the exact auth requirement, the error condition for JWT auth, and the prerequisite Proof account setup. This goes well beyond a minimal 'gets metadata' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and returned fields, then adds necessary edge-case and setup details. Every sentence carries useful information: what is returned, what is never returned, auth requirements, and access prerequisites. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema introspection tool, the description is complete. It explains what the agent gets, what it cannot get, how to authenticate, what error to expect when misused, and what environment setup is required. There is no significant missing information for correctly selecting and invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty and has 100% coverage, so there are no parameters to document. The description adds context about the implicit auth context (the calling API key), which is the relevant 'parameter' here. A score of 4 reflects that the baseline for a zero-parameter tool is strong and the description supports it well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clearly scoped resource: the calling API key's own redacted metadata. It even enumerates the returned fields and states it is for agent self-inspection, making the tool's purpose unmistakable and distinct from sibling tools like list_api_keys or get_api_key_usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions for use: API-key auth is required, and a JWT session will fail with 400 api_key_required. It also provides concrete setup steps (set PROOF_API_KEY, restart server) and warns that start_login does not enable this tool, giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It thoroughly explains the derived effective_status/is_valid semantics, when status diverges from stored values, why status=active can still return expired delegations, and the access requirement. This goes well beyond a generic listing description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main action is front-loaded, followed by essential caveats and an actionable ACCESS section. Every sentence adds information needed for correct use; there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description covers the critical return semantics, the filter limitation, the token retrieval alternative, and the access setup. An agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value for the status parameter, warning that it filters only the stored status and not the derived effective_status, which is a non-obvious pitfall an agent would otherwise miss.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'List your own delegations with optional filters.' It clearly scopes the operation to the caller's own delegations and distinguishes it from get_delegation, which retrieves a single delegation and its stored token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use get_delegation instead: tokens are not included in the list. It also states that there is no public enumeration of third-party delegations, and gives concrete access prerequisites (PROOF_API_KEY, restart, and that start_login does not open this tool).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses the real-world effect of sending a message, concurrency limits, 410 vs 404 semantics, and the email_sent=false retry signal. This goes far beyond a basic action statement and prepares the agent for non-obvious outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence earns its place: core purpose first, then rationale, user-confirmation requirement, channel exceptions, and edge-case response semantics. Front-loading the essential action and the 'do not call automatically' warning makes it highly usable despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with no output schema, the description covers all critical operational aspects: when a call is valid, what a 410 means, what a 404 means, how to handle delivery failure, and the one-session-one-email invariant. For a sensitive send action, this is complete enough for an agent to act correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the single parameter, so the baseline is 3. The description adds meaningful context by specifying that the id must come from an email-channel account-bootstrap session, which refines what value is valid even though it does not introduce new parameter syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Deliver the verification email') and a specific resource ('account-bootstrap session created with channel email'), and explicitly distinguishes itself from create_account, which sends nothing. This makes it immediately clear what the tool does and how it differs from its most relevant sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance: only for email-channel sessions, only after user confirmation, and never automatically after create_account. It also explains when not to use it for other channels and how to interpret repeat-call results, leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses channel-dependent return shapes, empty deep_link on SMS, possible missing or empty sms_dids entries, email_sent failure semantics, and the fragility of qr_text when wrapped. It also lists terminal session states, giving complete behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly structured with numbered agent steps and explicit channel-based branches. The core purpose and return fields are front-loaded, and every subsequent detail — including sms_dids edge cases and qr_text wrapping rules — is actionable rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, this description is unusually complete. It covers per-channel return values, follow-up polling with wait_for_login, terminal states, failure detection, and rendering constraints. An agent has enough information to invoke the tool correctly and handle all documented outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds essential cross-parameter meaning by clarifying that phone_number is required for SMS and email for email, and that the selected channel determines which returned fields are relevant. This goes beyond the schema's generic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — starting a login session by sending an authentication challenge — and enumerates the supported channels. It also distinguishes itself from related siblings by explicitly telling the agent to call wait_for_login afterward and referencing render_auth_link for presenting links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The numbered agent usage gives an explicit workflow: call start_login, then wait_for_login. It provides channel-specific instructions, including when to pass deep_link to render_auth_link versus showing sms_message, and warns that render_auth_link rejects the empty SMS deep_link. It also instructs checking email_sent before assuming email delivery, which is clear when/how usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers: authorization requirements, error response behavior, encryption mode selection, and environment setup via PROOF_API_KEY. It even warns that start_login does NOT open this tool, which is a non-obvious behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but organized into clear sections (overview, Agent usage, Encryption, ACCESS), with the core purpose front-loaded. Each paragraph adds necessary operational information; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a HITL confirmation creation tool with no output schema and no annotations, this description covers purpose, preconditions, failure handling, encryption complexity, follow-up polling, and access requirements. Nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents all three parameters, the description adds critical semantic depth: hitl_id must reference an authorized config, and message is not plaintext under E2E encryption but a JSON ciphertext envelope with v1/v2 selection rules and SDK guidance. This goes well beyond the schema field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first line states a specific verb and resource: "Create a HITL confirmation request." It then adds behavior that distinguishes it from related tools: it sends an approval request to configured channels and notes "First response wins." This clearly separates it from get_confirmation, wait_for_confirmation, and request_hitl_authorization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The "Agent usage" section gives explicit preconditions (HITL config must be authorized), error recovery (on 403 call request_hitl_authorization and wait for user approval), and post-actions (poll get_confirmation or use get_confirmation_approval_link). This is exactly the when-to-use guidance an agent needs, with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses this is a local computation with no HTTP request, clarifies that `qr_text` is rejected, and warns that QR text rows stop scanning if separated by blank lines or wrapping. These are behavioral details an agent needs to use the tool safely and correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose and key safety constraint ('no HTTP request') are front-loaded, and the longer agent-usage paragraph is dense rather than padded: every sentence earns its place by preventing a real misuse. The nested details are complex but justified by the need to route the correct link field from many sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description still explains what the agent will produce: a clickable link plus QR code inside a fenced code block. It also covers the edge case where only `qr_text` is available, which is essential for correct behavior in this domain. The description is complete for a simple local render tool with tricky input-source rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers the parameters 100%, the description adds high-value meaning for `url` by mapping it to concrete upstream fields and by explicitly excluding `qr_text`. It also clarifies the optional `label` role implicitly through the schema example; the description's source-field guidance goes well beyond the schema's generic 'e.g. a deep_link response field.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Render an authorization or verification URL as a clickable link followed by a scannable QR code inside a fenced code block.' It also distinguishes this local formatting tool from network or fetch tools by stating 'no HTTP request is made.' This is enough to tell it apart from sibling verification/render tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Agent usage' section explicitly tells the agent which link fields to pass from which earlier tools and channels, and even names the exact fields (`deep_link`, `challenge.deep_link`, `telegram_deep_link` / `whatsapp_deep_link`). It gives a clear when-not: 'Do NOT pass `qr_text` to this tool,' with an explicit alternative of printing `qr_text` verbatim in a fenced code block.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: the backend enforces a different channel than the login channel, TTL caps and forced single-use differ by action type, the email flow can return a no-session-started selection state, and qr_text must not be passed to a link renderer. These are exactly the non-obvious behavioral traits an agent needs to invoke the tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries operational value: policy constraints, channel-specific rendering rules, an email edge case, and a numbered agent workflow. It is structured from core purpose to policy to actionable steps, with no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has no output schema and no annotations, yet the description covers the critical response behaviors: deep_link, sms_message, requires_email_selection, available_emails, and qr_text handling. It also explains the grant/TTL mechanics and names the related downstream tools (wait_for_2fa, render_auth_link), making it fully actionable for a complex multi-step flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial meaning beyond the field docs: it explains when single_use is forced vs caller-chosen, how ttl_seconds is capped per scope and defaults, and why channel must differ from the login channel. It also connects email_id and the requires_email_selection response state, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Start a 2FA challenge that grants the authenticated user permission to perform a sensitive action.' It further clarifies the mechanism (grant keyed by user id and action_type, read by middleware), making the tool's unique role unmistakable and distinguishing it from generic 2FA tools like start_2fa or verify_2fa.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 5-step agent workflow: attempt the sensitive call, handle 403 2fa_required, call this tool with the correct action_type and channel, present the challenge per channel, wait for verification, then retry. It also gives exclusions ('start_login does NOT open this tool') and handles an edge case where email selection requires a second call instead of telling the user to check their mailbox.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

@proof-holdings/mcp-server MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![@proof-holdings/mcp-server MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ProofHoldings/mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/ProofHoldings/mcp-server)

Score Badge

Copy to your README.md:

[![@proof-holdings/mcp-server MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ProofHoldings/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/ProofHoldings/mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ProofHoldings/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server