Agentic Endpoints

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

Annotations already mark the tool as read-only and idempotent, and the description adds meaningful extra context: it preserves whole sentences, reports before/after token estimates, and discloses the $0.005 USDC payment on Base via x402. This is strong behavioral transparency, though it does not cover edge-case behavior such as overly small token budgets.

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

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

The description is two tight sentences with no filler. The core purpose is front-loaded, and the cost/payment detail is presented as a separate concise clause.

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

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

Given the complete input schema, the available output schema, and annotations, the description covers purpose, behavior, reporting, and cost. Nothing essential for selecting or invoking the tool is missing.

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

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

The input schema fully documents all three parameters at 100% coverage, so the description does not need to restate them. The description adds no per-parameter nuance beyond what the schema already provides, warranting the baseline score of 3.

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

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

The description clearly states a specific verb ('Reduce'), the resource ('text'), and the goal (fit a token budget), while also specifying behavioral details: preserving whole sentences and reporting before/after token estimates. It is easily distinguished from the sibling tools, none of which perform text compression.

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

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

The description conveys clear context: use this tool when text must be reduced to fit a token budget. It does not explicitly name alternatives or when-not-to-use cases, but no competing sibling exists and the intended use is easy to infer.

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

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

With annotations already indicating readOnly and idempotent behavior, the description adds valuable context: the 'content_missing' status meaning, the condition about queryable imports, and the exact cost and payment protocol. It also warns that a broken record should not be reported as an empty meeting, which is a meaningful behavioral nuance beyond the annotations.

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

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

The description is three sentences with no filler: it states the action, gives the usage context, flags an important status edge case, and mentions the cost. Every sentence adds unique value, and the most important information is front-loaded.

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

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

Given the rich input schema, output schema, and annotations, the description covers all essential operational aspects: what it fetches, when to call it, how to interpret an edge-case status, and the cost. Nothing an agent needs to correctly invoke this tool is missing.

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

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

The input schema already documents all three required parameters with 100% coverage, so the description is not required to add parameter details. It does not introduce any new semantic nuance beyond what the schema already provides. Baseline of 3 is appropriate because the schema fully carries the burden.

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

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

The description uses a specific verb ('Fetch') and identifies the exact resource ('a single meeting by meeting_id'), including the key behavior of returning the full transcript when queryable. It clearly distinguishes this tool from meetings_search and meetings_list by focusing on retrieval of one identified meeting rather than discovery.

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

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

It explicitly says to use this tool after meetings_search has identified the meeting, giving a clear ordering context. It also explains how to interpret a 'content_missing' status, preventing incorrect reporting. It does not explicitly mention when not to use it or name alternative tools, but the usage context is sufficient and clear.

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

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

With annotations offering no hints beyond non-read-only, the description carries the full burden and does so richly: it explains the privacy/searchability tradeoff, the required ciphertext/transcript pairing, the one-time namespace token, and the $0.004 cost paid via x402. 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.

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

The description is dense but every sentence earns its place: purpose, the central privacy decision, validation behavior, token recovery risk, and cost. It is front-loaded with the core action and then delivers high-value operational constraints without fluff.

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

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

For a tool with 9 parameters and subtle privacy semantics, the description covers the tricky decision points, the refusal behavior, the one-time token consequence, and the payment requirement. The output schema is noted as present, so the description need not enumerate return fields; nothing essential appears missing.

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

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

Schema coverage is 100%, but the description adds critical meaning beyond it: that visibility is a decision that cannot be guessed, that transcript only pairs with queryable and ciphertext only with private, and that mismatched combinations are refused. It also explains the namespace_token lifecycle, which is essential for correct multi-call usage.

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

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

The description states a specific verb and resource: 'Store a transcript so it can be searched later.' It clearly distinguishes this from the sibling search/list/get tools by emphasizing that this is the ingestion path, and the visibility modes further define the resource's behavior.

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

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

It gives clear context for when to use the tool: to store a transcript for later search. It does not explicitly name alternatives or say 'instead of meetings_search' but the import vs. search distinction is strongly implied by the wording and sibling list.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral details beyond those: it never returns transcripts, results are newest-first, and there is a $0.001 cost via x402. These are useful operational facts an agent needs to know before calling the tool.

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

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

The description is three sentences with no filler. The core behavior is front-loaded, followed by an important exclusion (no transcripts), then the use case and cost. Every sentence earns its place.

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

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

Given that an output schema exists and annotations cover safety/idempotency, the description is largely complete. It includes privacy behavior, cost, ordering, and the search alternative. It could have briefly noted the namespace_token requirement, but the schema already covers that parameter.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds mild context by framing the operation as listing within a namespace, but it does not add parameter-level detail beyond 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.

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 the meetings in a namespace newest first,' with the returned fields enumerated (titles, dates, participants, searchable flag). It also differentiates itself from meetings_search by noting that private meetings are invisible to that search tool, so an agent can distinguish the two.

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

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

The description gives explicit usage context: 'useful for orienting before a search' and 'for finding meetings that are private and therefore invisible to meetings_search.' This tells the agent when to prefer this tool over meetings_search without needing to infer the distinction.

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

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

Annotations already mark this readOnly and idempotent, and the description goes well beyond them by disclosing return fields (searched_meetings, private_meetings_skipped), the privacy/encryption limitation, the meaning of a zero search count, and the per-call cost via x402. 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.

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

Although slightly longer than average, every sentence earns its place: the core purpose is front-loaded, followed by usage examples, the critical private-meeting caveat, a routing pointer, and cost. There is 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.

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

For a search tool with four parameters, an output schema, and rich annotations, the description is complete. It covers behavior, edge cases, follow-up routing, and cost. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Input schema covers 100% of the parameters, so the baseline is 3. The description adds real value by explaining the query parameter's FTS5 behavior, recommending quoted phrases, and advising distinctive keywords over full sentences, which helps the agent construct better queries.

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

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

The description clearly identifies the tool as semantic search over imported meeting transcripts, with the specific verb 'Ask a question' and resource 'every meeting you have imported as queryable'. It distinguishes itself by positioning against meetings_get: use this to find the right excerpt, then use meetings_get to read the full transcript.

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

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

Explicitly states when to use: when the user refers to something said, agreed, or decided in a call, with concrete example queries. It also gives an important exclusion: private meetings are encrypted and cannot be searched, and explains the empty-result caveat. It routes to the correct sibling for follow-up reading of full transcripts.

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

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

Annotations already mark the tool as non-readonly, non-destructive, and idempotent, and the description consistently matches. It adds substantial behavioral context: atomicity, strongly consistent Durable Object backing, lease semantics, retry_after/expires_at behavior, cost, and the warning that this cannot be safely reimplemented locally.

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

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

Every sentence carries operational weight: purpose, timing, return-state semantics, infrastructure guarantee, and cost. The most decision-relevant information is front-loaded, and the return-state explanation is compact despite covering five distinct outcomes.

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

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

The description is complete for the tool's complexity: it explains when to call it, what each possible result means, what to do next, why it is safe and consistent, and what it costs. With an output schema present, the description appropriately focuses on decision-making context rather than return-value shape.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable parameter-related meaning for payload_sha256 and lease_ttl by explaining that a different payload hash triggers a conflict and that 'in_progress'/'held' outcomes correspond to lease behavior. This goes beyond merely restating schema text.

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

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

The description states a specific verb and resource: it 'Claims a {namespace, action_key} pair exactly once' as an 'Atomic idempotency witness.' This clearly differentiates it from sibling tools by focusing on the claiming operation and explicitly references once_key_complete for follow-up, so an agent can identify what this tool does and how it differs from related tools.

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

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

It gives explicit timing guidance—'Call this BEFORE any non-idempotent action'—and tells the agent exactly what to do on each return state, including not doing work. It does not explicitly mention when to prefer once_key_release or list exclusion conditions, so it narrowly misses full alternative routing.

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

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

The description goes beyond annotations by disclosing that completion is final and cannot be overwritten, that later claims return 'duplicate' with the recorded result, and that recording is what allows another agent to continue. It also notes the tool is free. These are meaningful behavioral traits not captured by annotations alone.

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

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

The description is front-loaded with the core purpose and immediate cost signal ('Free'), then explains consequences and finality. It is slightly redundant by stating 'Free' at the start and again at the end, but overall every sentence earns its place.

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

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

Given the output schema exists and parameter coverage is 100%, the description supplies all necessary behavioral context: when to call, what happens afterward, how it affects other agents, and finality. No critical operational detail is missing for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds only minimal reinforcement ('action_key you claimed', 'result' of the work) and does not need to compensate for missing parameter documentation.

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

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

The description gives a specific verb ('Records'), a clear resource ('the result of work you performed under a claim from once_key_claim'), and distinguishes it from the related once_key_claim tool by explaining the post-claim completion role. This is immediately clear and differentiated.

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

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

It explicitly states when to call the tool: 'Always call this after the work succeeds.' It also explains the consequence of not calling it, which guides correct usage. It does not mention the alternative failure path via once_key_release, but the primary usage condition is clear.

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

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

Discloses a key refusal behavior: releasing an already completed key is refused because it would discard the recorded result and risk running the side effect twice. This goes beyond the annotations by explaining failure semantics and safety rationale. 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.

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

Mostly efficient and informative, but the free/no-payment point is stated twice ('Free.' and 'This tool is free; no payment is required.'), wasting a sentence. Otherwise tightly written and front-loaded.

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

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

For a moderate-complexity tool with full schema coverage and an output schema, the description covers what the tool does, when to call it, and the important refusal behavior. An agent has enough to invoke it correctly and avoid dangerous misuse.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description adds little param-specific detail, but the baseline of 3 applies because the schema carries the load.

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

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

States a specific verb ('surrenders'/'release') and resource ('claimed action_key'), with a clear effect: letting a retry start immediately. This distinguishes it from sibling claim/complete operations even though those tools aren't named.

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

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

Explicitly says 'Call this when the work you claimed fails' and explains the benefit over waiting out the lease. It does not name an alternative tool for success cases, but the condition is clear enough.

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

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

The description goes well beyond the readOnlyHint annotations by revealing important behavior: it handles compressed streams, PDF 1.5+ object streams, and ToUnicode CMaps, and honestly reports encrypted or image-only documents instead of returning garbage. It also discloses the cost and payment protocol, which is material side-effect information.

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

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

Three focused sentences: core function, technical robustness and honesty guarantees, and cost/payment. Every sentence earns its place, and the most important usage information is front-loaded.

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

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

With a rich output schema, 100% parameter coverage, and annotations covering read-only/idempotent behavior, the description fills the remaining gaps: failure honesty, format support, and cost. An agent has everything needed 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.

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

Schema description coverage is 100%, with both url and max_pages already documented. The description adds no additional parameter-level meaning beyond 'by URL,' so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Extract text from a PDF by URL.' It clearly defines what the tool does and is immediately distinguishable from siblings like scrape or compress.

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

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

The description gives clear context for when to use the tool: whenever text extraction from a PDF at a URL is needed. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can route to it confidently.

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

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses concrete behavioral constraints: SSRF-style address refusals, per-hop redirect re-validation, and a specific monetary cost via x402. This materially helps an agent predict side effects and prerequisites.

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

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

Two sentences, both purposeful: the first states the operation and options, the second adds security and cost constraints. Every sentence earns its place and no filler exists.

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

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

Given the annotations, output schema, and full parameter documentation, the description covers the remaining operational essentials: what it fetches, how to narrow, security restrictions, redirect behavior, and cost. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents url, format, and selector. The description adds only interpretive flavor ('readable text', 'optionally narrowed by selector') without providing substantive new parameter meaning.

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

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

The description uses a specific verb ('Fetch') with a resource ('a URL') and states the output ('readable text or markdown'), making the core function unambiguous. It inherently differentiates from siblings like pdf_parse by resource type.

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

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

The description makes the general usage context clear and states that private, loopback, and link-local URLs are refused, which is an explicit when-not condition. It does not name alternative tools or scenarios where a sibling would be preferred, so the guidance falls short of explicit routing.

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

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

The description adds valuable behavioral context beyond the annotations: the operation is permanent, requires a one-time namespace_token, and costs $0.005 USDC on Base via x402. This aligns with the destructiveHint=true annotation without contradicting it. The irreversibility warning is genuinely useful for an agent, though the description could have expanded on the payment failure behavior.

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

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

Two concise, information-dense sentences. The permanent, destructive nature is front-loaded, followed by the required token and cost. Every word contributes value and there is no redundancy.

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

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

Given the destructive annotation, idempotent hint, and 100% schema coverage, the description covers the essential operational details: irreversibility, required token, and cost. A small gap is the lack of detail about the x402 payment flow or failure consequences, but the current information is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description does not add additional semantic 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.

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

The description states a clear verb and resource: 'Permanently delete an item.' The title clarifies it deletes a stored secret, which distinguishes it from sibling tools like vault_retrieve and vault_list. However, it doesn't explicitly name the sibling it is not, so it relies on the delete semantics for differentiation.

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

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

The description identifies a key prerequisite ('Requires the namespace_token') and a practical cost consideration, both useful for deciding whether to invoke. It doesn't explicitly state when not to use it or name alternatives, but the destructive nature and token requirement provide clear usage context.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: it costs $0.001 in USDC via x402 and requires the namespace_token. It also explicitly states that ciphertext is not returned, which is a meaningful behavioral guarantee beyond the annotations.

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

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

Two sentences with no filler. The core behavior is front-loaded, followed by the auth requirement and cost. Every clause earns its place.

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

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

For a simple existence-check tool, the description covers the essential context: what it does, what it avoids returning, the required token, and the cost. The output schema covers return values, and annotations cover read-only/idempotent behavior. Nothing important is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description only reiterates that namespace_token is required, which adds no new semantic meaning beyond 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.

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

The description states a specific verb ('Check for a key') and resource, and clarifies that it does not return ciphertext, which sharply distinguishes it from vault_retrieve and vault_list. The title 'Test whether a key exists' reinforces the exact purpose.

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

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

The description implies when to use this tool: when you need to verify a key's existence without retrieving its ciphertext. It also notes the namespace_token requirement. It does not explicitly name alternative tools or state when not to use it, 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.

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint false; the description adds meaningfully beyond that: it never returns ciphertext, updated_at is the version to pass as if_match on conditional stores, and the call costs $0.001 USDC on Base via x402. There is no contradiction with the annotations.

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

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

Every sentence earns its place: primary behavior first, then the ciphertext restriction and alternative, then the if_match version detail, then usage context and cost. It is tight, front-loaded, and free of redundant filler.

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

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

The input schema covers both required parameters, the output schema covers the return shape, annotations cover safety and idempotency, and the description covers purpose, alternatives, cost, and version semantics. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so namespace and namespace_token are already documented. The description does not add material parameter-level meaning beyond the schema; it references namespace in context but adds no new syntax, format, or parameter-specific guidance.

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

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

The description names the exact resource (keys in a vault namespace) and the action (list), and adds that it returns metadata only, never ciphertext. It explicitly contrasts itself with vault_retrieve, so an agent can distinguish it from sibling tools immediately.

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

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

It gives a clear usage trigger ('Use this when you have stored secrets and need to know what is there') and an explicit alternative ('use vault_retrieve for that' when ciphertext is needed). This gives an agent enough direction to choose correctly without opening other tool definitions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations by disclosing the $0.02 USDC cost on Base via x402 and the namespace_token requirement. No contradiction with annotations exists.

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

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

The description is two sentences with no filler. It front-loads the core purpose and then provides the two most important operational details: the token requirement and the cost. Every sentence earns its place.

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

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

Given the full parameter schema, output schema, and annotations, the description covers the missing context: cost, payment protocol, network, and token prerequisite. Nothing critical is absent for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, and all three parameters have clear descriptions in the input schema. The description only briefly mentions namespace_token as required, which adds little beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description uses a specific verb+resource pair, 'Retrieve a previously stored ciphertext,' which clearly states the tool's function. It is distinguishable from sibling tools like vault_store, vault_delete, and vault_list even without explicitly naming alternatives.

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

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

The description clearly signals when to use this tool: to retrieve a previously stored ciphertext. It also provides an important prerequisite, 'Requires the namespace_token,' which helps the agent understand the call context. However, it does not explicitly contrast with sibling tools or state when-not-to-use.

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

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

Annotations mark the operation as destructive and non-read-only, and the description goes further by disclosing immediate invalidation, irreversibility, the need to present the current token, and permanent unrevocable access if leaked. This adds significant behavioral context beyond the annotations.

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

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

The description is front-loaded with the core behavior and risk in compact sentences. It is slightly padded by repeating 'free' at the start and again at the end, but the overall structure is efficient.

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

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

With both parameters fully documented in the schema and an output schema present, the description covers everything needed to decide and invoke correctly: trigger conditions, required authorization, consequences, and irreversibility.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the namespace_token must be the current token and that rotation produces a new one, disambiguating the schema's 'first call' phrasing.

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

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

The description states the exact action—'Mints a new namespace_token and immediately invalidates the current one'—on a specific resource. It is unambiguous and clearly distinct from sibling tools like vault_delete or once_key_claim.

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

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

It explicitly says when to use the tool ('whenever the token may have been exposed') and explains the stakes if you don't. It does not mention alternatives or explicitly state when not to use, preventing a 5.

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

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

Even with annotations indicating mutation and destructiveness, the description adds substantial non-obvious behavioral context: the service never sees plaintext, but stores key/namespace/alg/size in the clear; the namespace_token is shown only once and cannot be recovered; concurrent writes return 'precondition_failed' instead of silently overwriting; and each call costs $0.02 via x402. There is no contradiction with the annotations.

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

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

The description is dense but every sentence carries essential operational or security information. It front-loads the core purpose and privacy caveat, then covers token handling, concurrency guards, and cost. There is no fluff or restatement of the title.

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

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

For a tool with 8 parameters, concurrency controls, a one-time token, security caveats, and payment requirements, the description covers all critical invocation facts. The output schema exists, so missing return-value details are acceptable. Nothing important for correct use is left unexplained.

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

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

Input schema covers all 8 parameters at 100%, so the baseline is 3. The description adds meaningful value by explaining the namespace_token lifecycle, compare-and-swap semantics, and the client-side encryption requirement. Some details are redundant with schema descriptions, so a 4 rather than 5.

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

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

The description opens with a specific verb and resource: 'Store client-side encrypted data.' It clearly distinguishes this from sibling operations like vault_retrieve, vault_list, and vault_delete. The title reinforces the core action, leaving no ambiguity about what the tool does.

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

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

The description gives concrete usage guidance: the first store claims the namespace and returns a one-time namespace_token that must be saved, and it explains when to use if_match versus if_absent to avoid clobbering concurrent writes. It does not explicitly name alternative sibling tools or provide when-not-to-use guidance, which prevents a 5.

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