Agentic Endpoints

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

The description discloses a behavior not present in annotations: the call costs $0.010 paid via x402 or a credit token, plus it promises whole-sentence preservation and before/after token estimates. These are meaningful runtime traits beyond the readOnly/idempotent hints, and 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?

Two sentences with no filler: the first states the operation and its guarantee, the second states cost and payment alternatives. The most important information is front-loaded and every clause supports an invocation decision.

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

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

With an output schema present and full parameter documentation in the schema, the description needs only to add what schemas don't show: cost, payment route, and the credits_trial fallback. It covers those; a small gap is that it doesn't mention the strategy default, but that is already in the input schema.

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

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

Schema description coverage is 100%, so the schema already documents text, strategy, credit_token, and target_tokens. The description adds only high-level context (whole-sentence preservation, cost) rather than new parameter-level detail, matching the baseline for full schema coverage.

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

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

Description opens with a specific verb and object ('Reduce text') and defines a precise goal: fit a token budget while preserving whole sentences and reporting before/after estimates. This clearly separates it from siblings like meetings_summarize and names the resource it acts on.

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

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

It supplies important context for when to use the tool (when text must fit a token budget) and directly handles the payment prerequisite by pointing to credits_trial. It does not explicitly exclude alternatives or tell an agent when not to use compress, so the guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description does not contradict them. It adds useful behavioral context that the tool is free and intended as a diagnostic check, which goes beyond the structured 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 short and front-loaded, but the word 'free' appears twice: once in the opening sentence and again in the final sentence. This redundancy means not every sentence earns its place, though the overall length is still appropriate.

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 single parameter, full schema coverage, existing output schema, and annotations covering safety traits, the description is complete. It includes the key diagnostic purpose and cost 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.

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 the credit_token parameter. The description adds no additional parameter-level meaning beyond calling it a credit token, which aligns with 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 it reports the remaining balance on a credit token, using a specific verb and resource. It does not explicitly differentiate itself from sibling tools like credits_trial, so it falls just short of a 5.

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

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

The description gives a clear use case: distinguishing 'out of credit' from 'the call failed'. It does not mention when not to use the tool or name alternatives, but the diagnostic purpose is clear 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.

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

Annotations say readOnlyHint=false but idempotentHint=true and destructiveHint=false, which aligns with 'one allowance per caller' returning the same token without side effects. The description adds high-value context beyond annotations: no wallet, signature, account, or email required; no x402 payment; the exact value and approximate call count; and the non-refill behavior. It clarifies the stateful allowance semantics and downstream token use.

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

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

It is front-loaded with the core value (free, first tool to call), then covers return value, usage, limits, and alternatives in four compact sentences. Every sentence adds unique information without repetition or 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 zero-param, free tool with an output schema, the description covers purpose, usage, return value semantics (token and value), limitations (one allowance, no refill), and the alternative purchase path. It is complete enough for an agent to invoke and use it correctly.

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

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

There are zero parameters, so baseline is 4. The description explains how to use the returned credit_token as an argument to paid tools, which is useful integration guidance beyond the empty schema. No parameter syntax is needed, but it could mention whether the token is passed as a string or object if relevant.

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 grants free credit and returns a credit_token worth $0.10. It also distinguishes itself from siblings by naming itself as the first tool to call when another tool reports payment required, and explicitly contrasts with /credits/buy as the refill path.

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 when-to-use guidance: call this first if any tool says payment is required. It also states when not to expect more: one allowance per caller, asking again returns the same token, and refills come from /credits/buy. This is precise 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?

Beyond the annotations (readOnly, idempotent), the description discloses the conditional transcript inclusion ('when it was imported as queryable'), the meaning of 'content_missing' as a broken record rather than an empty meeting, and the concrete $0.005 cost with x402/credit token alternatives. These are exactly the behavioral details an agent needs that the schema cannot convey.

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

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

Four sentences, each doing distinct work: scope, usage ordering, error interpretation, and payment. It is front-loaded with the primary purpose and contains no filler or repeated schema information.

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

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

For a single-record read tool, the description covers when to call it, what is included, how to interpret a problematic response, and how the call is paid. The presence of an output schema means return-value detail is not needed in the description, and annotations cover safety and idempotency.

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

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

Schema description coverage is 100%, with every parameter already explained, including the meaning of meeting_id and credit_token. The description adds no new parameter-level syntax or constraints, so per the baseline rule it scores 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 opens with a specific verb and resource: 'Fetch a single meeting by meeting_id, including its full transcript.' The phrase 'after meetings_search has identified the meeting you want' distinguishes it from the search sibling, and the title reinforces the one-record scope. This is unambiguous and immediately telegraphs the tool's niche.

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 'Use this after meetings_search has identified the meeting you want,' giving a clear when-to-use directive. It also covers the payment fallback path via credits_trial. However, it does not explicitly contrast with meetings_list or state when not to use it, so it earns a 4 rather than a 5.

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

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

The description goes well beyond the annotations, which only say the operation is not read-only, not open-world, not idempotent, and not destructive. It discloses concrete behavioral consequences: the first import creates a namespace_token shown exactly once, losing it makes the namespace unrecoverable, the call costs $0.010, private imports are never searchable, and mismatched transcript/visibility pairs are refused. This is rich, honest 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.

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

The description is long but every sentence earns its place: purpose, input format flexibility, privacy/searchability trade-offs, one-time token handling, and cost/payment. It is front-loaded with the core purpose and then builds outward into operational details. There is no filler or redundant restating of the schema.

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

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

Given the tool's complexity, the description covers almost everything an agent needs: raw format handling, cue merging, visibility semantics, namespace token persistence, and payment. An output schema exists, so detailed return values do not need to be explained. The only notable gap is the inconsistency between the description's claim that visibility is required and the schema's optional default, which leaves room for agent misinterpretation.

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 already solid. The description adds valuable cross-parameter semantics: transcript is paired with 'queryable', ciphertext with 'private', namespace_token is required for later calls, and credit_token is an alternative payment path. However, it creates some confusion by calling visibility a 'required decision that cannot be guessed' while the schema lists it as optional with a default of 'private'. This tension prevents a top score.

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 immediately states a specific action and resource: 'Store a transcript so it can be searched later.' It also explains that raw WebVTT/SRT inputs are accepted directly, which clearly distinguishes this ingestion tool from sibling tools like meetings_get, meetings_search, and meetings_summarize. It is not a tautology and meaningfully expands on the title.

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 strong contextual guidance: it says when to use the tool (raw transcript from Zoom/Teams/Meet/notetaker), removes a common preprocessing burden, and even routes users without credit to credits_trial. However, it does not explicitly state when to prefer this tool over related siblings like vault_store or compress, so it stops short of full when-not/alternatives guidance.

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

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

The description substantially extends the annotations: it reveals the newest-first ordering, the transcript-exclusion behavior, the ability to list private meetings, and the exact cost/payment paths including the credits_trial fallback. None of this contradicts the readOnly, idempotent, or openWorld 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: core behavior, key limitation, usage context, and payment instructions. The description is front-loaded with the action and result shape, and it is not padded with redundant restatements of the title or schema.

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

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

Given the output schema and full parameter documentation, the description is complete enough for an agent to select and invoke the tool correctly. It covers ordering, visibility scope, the transcript limitation, cost, payment options, and how to get free credit, leaving no critical operational gap.

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

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

Schema description coverage is 100%, with each parameter already documented meaningfully. The description adds no extra parameter-level semantics, so the baseline of 3 applies rather than requiring compensation for missing schema detail.

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

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

The description names a specific verb ('List'), a resource ('meetings in a namespace'), and the exact fields returned: titles, dates, participants, and searchable status. It also differentiates itself from meetings_search by stating it can surface private meetings that search cannot see.

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 use cases: orienting before a search and finding private meetings invisible to meetings_search. It also states that transcripts are never returned, which is a useful exclusion, though it does not explicitly name meetings_get as the alternative for transcript retrieval.

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

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

The annotations already mark the tool read-only and idempotent, and the description adds substantial beyond that: private meetings are encrypted and skipped, searched_meetings=0 means nothing was searched rather than the topic never arose, and the call costs $0.010 paid via x402 or credit token. These are exactly the non-obvious behaviors an agent needs to interpret results and avoid surprise payment failures.

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: purpose, use-case triggers, return-value caveat, sibling routing, and cost disclosure. It is front-loaded with what the tool does and only then adds caveats, with no filler or repetition.

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 an output schema already present, the description covers all essential operational context: ranking behavior, private-meeting exclusion, empty-result interpretation, cost, payment method, and fallback credit path. An agent has everything it needs to select, call, and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including FTS5 match syntax, namespace/token requirements, and the optional credit_token. The description reinforces high-level usage but does not need to add parameter-level detail; baseline 3 is appropriate.

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

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

States a specific verb and resource: asking a question across imported meetings and receiving ranked excerpts with the meeting source. It clearly distinguishes itself from meetings_get, which reads a full transcript, and the example queries make the search intent concrete.

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 this tool: whenever the user references something said, agreed, or decided in a call. It also routes to meetings_get for reading a full transcript after the right meeting is found, and warns that private meetings cannot be searched, setting correct expectations.

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, openWorldHint, and idempotentHint, and the description adds substantial behavioral context beyond them: no_matches means no answer was generated, zero searched_meetings means everything private and nothing read, private meetings are encrypted and skipped, truncated meetings cannot serve as evidence, and the cost/payment model. 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 longer than average but every sentence earns its place: purpose, usage rule, anti-pattern warning, failure semantics, privacy caveat, truncation caveat, and cost. It is front-loaded with the core action and differentiator, then layers critical operational warnings that directly affect how an agent should interpret results.

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, the description need not explain return structure, and it instead covers the non-obvious semantics an agent needs to reason correctly: what no_matches and searched_meetings:0 really mean, the limitation of private and truncated meetings, and the payment path. Nothing needed for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that question is plain language, not a search syntax, that the terms actually searched come back for verification, and that credit_token can pay from a balance obtained via credits_trial or /credits/buy. This supplements structure without repeating it.

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: ask a plain-language question and get a written answer grounded in meeting transcripts with cited meeting ids. It explicitly differentiates from meetings_search by describing the exact user intent that selects this tool, so an agent can distinguish it without opening the sibling schema.

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

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

Gives explicit when-to-use guidance: prefer meetings_summarize over meetings_search when the user wants an answer rather than a list of excerpts to read. It also instructs to pass the question exactly as the user asked it and explicitly warns that this is not FTS5 syntax, which prevents a common misuse.

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

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

Annotations only provide basic flags (readOnlyHint: false, idempotentHint: true). The description goes far beyond that by explaining the underlying consistency (strongly consistent Durable Object), cost details ($0.010 USDC), payment methods (x402 or credit token), lease semantics (lease_ttl vs ttl, abandonment, takeover), and the meaning of 'held' (key stays locked until expires_at). It also clarifies that 'conflict' indicates a key derivation error. None of these are in the annotations, and there is no contradiction.

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 long but every clause earns its place. It opens with the core purpose, then the invocation timing, then the return-value contract, then cost/payment. The information is dense yet logically ordered, with no fluff. For a tool with five distinct outcomes and a payment model, this level of detail is necessary and well-structured.

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

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

Given the complexity (7 params, 5 return states, payment integration), the description is remarkably complete. It covers all return values, retry behavior, lease expiration, cost, payment fallback, and the recommendation to use credits_trial. It even notes what not to do in each scenario. An agent has everything needed to invoke this correctly without further investigation.

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 schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the relationship between lease_ttl and ttl, the consequence of omitting lease_ttl (hold for full ttl), the requirement of namespace_token for later calls, and the conflict semantics tied to payload_sha256. It doesn't restate each parameter's schema description but gives usage-oriented context that helps an agent choose and set them correctly.

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 ('claims'), a concrete resource ('{namespace, action_key} pair'), and the exact purpose: to ensure a side effect is performed exactly once across a fleet of agents. It distinguishes itself from siblings like once_key_complete and once_key_release by clarifying that this is the entry point before any non-idempotent action. The primary behavior is unmistakable.

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 'Call this BEFORE any non-idempotent action' and lists concrete examples (email, charge card, post order). It then enumerates the five possible return values and the precise action an agent should take for each (e.g., wait retry_after seconds, use the result, do not do the work). It also mentions the fallback to credits_trial for free credit and warns against reimplementation. This leaves no ambiguity about when and how to use it.

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

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

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?

Annotations already mark the tool as read-only, idempotent, and open-world. The description adds valuable behavioral disclosures beyond that: how it handles compressed streams, PDF 1.5+ object streams, ToUnicode CMaps, and that it returns honest diagnostics for encrypted or image-only PDFs instead of garbage. It also surfaces the cost and payment flow, which materially affects invocation.

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

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

Two sentences with no filler. The first sentence states the core action; the second packs meaningful capability, failure behavior, and payment details. Every sentence earns its place 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?

For a read-only extraction tool with a full output schema, the description covers what the tool does, what PDF complexities it handles, how it behaves on problematic inputs, and how to pay. The only implicit requirement, that the URL be HTTPS, is already specified in the schema. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a little color around the credit_token payment flow and 'by URL' framing, but it does not significantly extend parameter 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 opens with a specific verb and resource: 'Extract text from a PDF by URL.' It clearly identifies the tool's core function and distinguishes it from sibling tools like scrape or meetings_* by being PDF-specific and text-extraction-focused.

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 clear when the tool applies (PDFs by URL) and provides practical context about payment methods and the credits_trial alternative. It does not explicitly name excluded cases or alternative tools, but the purpose is specific enough that the usage context is evident.

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

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

Goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing that private addresses are refused, that AI-crawler robots.txt behavior and /llms.txt presence are probed, and that POST-body preservation across http-to-https redirects is tested. It also states the exact cost ($0.010 USDC on Base), the payment mechanism (x402 or credit token), and the free-credit fallback.

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

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

Purpose and client list are front-loaded in the first sentence, with secondary behaviors and payment details following. The nine-client parenthetical is long but each entry is informative rather than filler; overall it earns most of its length for a tool with this many facets.

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?

A read-only tool with an output schema and full annotation coverage needs no return-value documentation, and the description still explains what categories of findings appear and what it will not do (private addresses). Authentication/payment prerequisites are fully covered, so an agent has everything required to invoke it.

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

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

Schema description coverage is 100%, so the schema already explains both url and credit_token, including the token's origin and purpose. The description only adds the pricing context around credit_token and the private-address restriction on url, which is useful but marginal against a fully documented schema.

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

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

The description names a specific action (send one GET as each of nine named clients) and the exact resource (a URL), plus the concrete outputs it reports (refusals, robots.txt AI-crawler blocks, /llms.txt, POST-body redirect behavior). It does not, however, distinguish itself from siblings like reach_report, reach_report_rescan, or reach_report_status, so an agent must infer the difference between a one-off check and a persistent report.

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

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

"Use before relying on a site or API from code, or to check your own" gives explicit context for when to call it, and the closing sentence routes to credits_trial when the caller lacks payment. No exclusion criteria or direct sibling comparison (e.g., when to prefer reach_report for ongoing monitoring) is provided.

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

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

Annotations only declare a generic non-readonly, non-destructive profile (openWorldHint=false, idempotentHint=false), which is thin for an async paid batch job. The description adds the crucial behavior: a report_id/report_url is returned immediately while scanning happens in the background (~10s per page), the deliverable contents, three free re-scans in 30 days, and the exact payment rails (x402/USDC on Base or credit token).

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

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

Front-loaded with the core action and delivery model, and nearly every sentence carries distinct information (async timing, report contents, read-back tool, alternative tool, pricing). Minor redundancy between the title's '$69' and the trailing 'Costs $69.00' sentence keeps it from a 5.

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

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

For a paid, async, multi-url tool the description covers delivery semantics, cost, payment paths, follow-up tools, and alternatives. An output schema exists, so it correctly does not need to enumerate return fields.

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

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

Schema description coverage is 100%, so both parameters (urls, credit_token) are already documented in the schema, including the 1-20/3-hostname limit. The description adds only a general mention of credit-token payment, which the schema already covers in more detail; baseline 3 applies.

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

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

States a specific verb and resource ('Order a full reachability report for one site') plus concrete scope ('up to 20 pages, each checked from nine common clients'). It also explicitly contrasts itself with the sibling tools reach and reach_report_status, so an agent can route without opening a schema.

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

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

Explicit when-to-use routing: 'Use reach_report_status to read it' and 'For a single quick check use the reach tool instead.' It even handles the no-payment prerequisite by naming credits_trial for free credit, which removes the most likely invocation failure.

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 it is not read-only, not idempotent, not destructive, but say nothing about cost or limits. The description adds genuinely useful behavior beyond them: it is free, capped at three uses within 30 days of ordering, and no payment is required — real quota and billing context an agent could not infer from the annotations.

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

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

Front-loaded with the key constraint and the core behavior, but the last sentence ('This tool is free; no payment is required') restates the opening 'Free' clause, wasting space on a duplicate rather than adding information.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on purpose, quota, and outcome. For a one-parameter tool with annotations, this is essentially complete; only explicit sibling routing is absent.

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

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

Schema coverage is 100% and the single report_id parameter is fully documented in the schema as 'the report_id of a finished report'. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

Specific verb+resource: 'Re-runs every page of a finished report' names the action and the target precisely, and the 'after fixing / confirm a fix worked' framing separates it from reach_report (create) and reach_report_status (poll). An agent can select it without opening the schema.

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

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

The trigger condition is clear: run this after a fix to confirm it worked on a finished report. The quota ('up to three times within 30 days of ordering') implicitly bounds when it can be used. It does not explicitly name alternative tools such as reach_report_status for checking progress, 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.

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so safety is covered. The description adds genuinely new context in a payment-oriented toolset: it is free and requires no payment, stated twice. It also discloses the stateful return behavior (progress vs. findings, re-scan comparison), which annotations do not convey.

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

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

The return-content enumeration is well front-loaded and informative, but the payment claim is stated twice ('Free.' at the opening and again as 'This tool is free; no payment is required.'), which is pure redundancy. Removing the duplicate would leave a tight, high-value sentence.

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

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

An output schema exists, so return values need not be spelled out, yet the description usefully summarises the shape of results across the scanning and completed phases. Combined with complete schema coverage and annotations, an agent has enough to call this correctly; only the explicit relationship to sibling reach/reach_report_rescan is missing.

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

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

Schema description coverage is 100% and the single report_id parameter is fully documented there, so the schema carries the load. The description only restates that the report is addressed 'by its report_id' and adds no format, provenance or validation detail beyond the schema.

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

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

States a specific verb and resource ('Returns a reachability report by its report_id') and enumerates the two response states an agent will encounter: in-progress while scanning, then prioritised findings with causes, fix steps and reproducing commands. This also implicitly distinguishes it from sibling reach_report_rescan, which starts a new scan rather than reading one.

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 mention of 'progress while it scans' implies this is the tool to poll after ordering a report, and 'a comparison with the previous scan after a re-scan' hints at follow-up after reach_report_rescan. However, no alternative is named and no explicit when/when-not condition is given; the agent must infer the polling workflow.

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 readOnly/idempotent annotations, the description discloses SSRF protections ('private, loopback and link-local addresses are refused, and every redirect hop is re-validated') and a concrete cost/payment model ($0.010 USDC via x402 or credit token). These are non-obvious behaviors an agent must know before invoking.

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 sentences with no filler: main capability first, then security constraint, then cost/payment. Every sentence adds distinct value, and the structure front-loads the action an agent needs to identify the tool.

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

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

For a four-parameter tool with full schema coverage, an output schema, and readOnly/idempotent annotations, the description adds the missing operative constraints: network restrictions, redirect safety, and payment/credit behavior. Nothing essential for correct selection or invocation is omitted.

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, selector, and credit_token. The description adds lightweight context for selector ('narrowed by CSS selector') and payment, but does not materially extend the parameter semantics beyond what the schema provides; baseline 3 applies.

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

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

Description uses a specific verb-resource pairing: 'Fetch a URL and return readable text or markdown, optionally narrowed by CSS selector.' This clearly differentiates scrape from siblings like pdf_parse or meetings_search; an agent knows exactly what resource it acts on and what it produces.

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 tool's usage context is clear: fetching a URL for readable text/markdown, with optional CSS selector. It does not name competing tools for exclusion, but it does give conditional payment guidance ('call credits_trial for free credit if you have neither'), which helps an agent decide when a prerequisite is missing.

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

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

Beyond the annotations (destructive, idempotent, non-read-only), the description discloses key side effects: deletion is permanent, a namespace_token is required, and the call costs $0.005 in USDC paid via x402 or a credit token. This is exactly the kind of cost and access context an agent needs before executing a destructive operation.

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

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

Two compact sentences cover the action, precondition, cost, payment method, and fallback credit path with no filler. The essential destructive action is front-loaded, and every clause adds useful information.

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

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

Given the rich schema, the annotations (especially destructiveHint and idempotentHint), and the presence of an output schema, the description supplies the important missing context: payment side effects, required auth token, and the free-credit fallback. An agent has enough to decide whether to call this tool and what prerequisites must be satisfied.

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 four parameters comprehensively at 100% coverage, including the optional credit_token and the nature of the namespace_token. The description adds a helpful pointer to credits_trial for free credit, but it does not substantially expand parameter meaning beyond the schema.

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

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

The description opens with 'Permanently delete an item', giving a clear verb and resource, and the title narrows it to deleting a stored secret. This separates it from sibling tools like vault_store and vault_retrieve, leaving no ambiguity about what operation is performed.

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

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

It states the necessary precondition ('Requires the namespace_token') and when an alternative payment path applies ('call credits_trial for free credit if you have neither'). It does not explicitly discuss a when-not-to-use case or name a sibling alternative, but the destructive nature and token requirement provide sufficient context for an agent to invoke it correctly.

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

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

Annotations already indicate readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: it returns no ciphertext, requires the namespace_token, costs a specific amount, and explains the two payment paths. This goes well beyond the structured annotations, particularly around cost and authentication.

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 concise and front-loaded: the core behavior appears first, followed by the essential prerequisite and cost information. Every sentence adds necessary operational detail without redundancy or 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?

Given the output schema exists, return values need not be described. The description covers the key behavioral, authentication, and cost details needed to invoke the tool. It misses only explicit sibling differentiation for when to choose this over vault_retrieve, so it is nearly complete but not perfectly so.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the namespace_token requirement and references credit_token indirectly, but adds little semantic detail beyond what the schema already provides. This is adequate but not exceptional.

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: 'Check for a key' and explicitly notes it does so 'without returning its ciphertext,' making it clearly distinct from vault_retrieve. The title reinforces the existence-testing purpose. It is immediately obvious 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.

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

The description conveys clear context around prerequisites and cost, but does not explicitly name alternatives such as vault_retrieve or state when an agent should prefer this tool over them. The phrase 'without returning its ciphertext' implies an existence-only use case, but this is not made explicit enough for definitive 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 significant behavioral context beyond the annotations: it explicitly states the tool never returns ciphertext, lists the metadata fields returned (alg, size, timestamps), explains that updated_at serves as the version for conditional stores, and discloses the exact cost and payment mechanism. It does not contradict the readOnlyHint or idempotentHint 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?

Three sentences, each earning its place: the first states the core purpose, the second highlights the security boundary and alternative, and the third gives usage context and cost. Information is front-loaded 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.

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

The description covers purpose, constraints, alternative routing, practical usage ('updated_at ... as if_match'), and cost/payment options. Combined with the output schema and annotations, the agent has everything needed to decide when to call this tool and how to interpret its response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little parameter-specific meaning beyond the schema; it references credit tokens and namespace context but does not clarify any parameter beyond what the schema already states. This is adequate but does not go beyond the structured fields.

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 keys held in a namespace with their metadata'. It distinguishes itself from siblings by explicitly saying 'Never returns ciphertext — use vault_retrieve for that.' This makes it immediately clear what the 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?

The description gives explicit guidance: 'Use this when you have stored secrets and need to know what is there.' It also names the alternative tool for retrieval of secret values ('use vault_retrieve for that') and provides a conditional path for free credit via credits_trial. This is strong, actionable usage guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate that. It adds valuable behavioral context: the $0.02 cost on Base, the x402 payment requirement, the credit_token alternative, and the namespace_token prerequisite. It also clarifies this returns a ciphertext, not a decrypted secret.

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 fluff. The first sentence states the core action; the second covers prerequisites and cost, including a pointer to credits_trial. 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 read tool with full schema coverage, an output schema, and idempotent/read-only annotations, the description is nearly complete. It covers cost, prerequisites, and payment alternatives. Missing details like error behavior are minor and the output schema likely covers return values.

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 description doesn't need to repeat parameter details. The description does add context about the payment flow and the credit_token alternative, but it doesn't explain individual parameters beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a previously stored ciphertext.' This clearly distinguishes it from sibling tools like vault_list (list keys) and vault_exists (check existence). The phrase 'previously stored' also implies it is the counterpart to vault_store.

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 call it: to retrieve a stored ciphertext, and it specifies the required namespace_token and payment options. It does not explicitly name alternative tools or exclusion criteria, but the purpose is unambiguous enough that an agent can infer when it is appropriate.

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

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

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?

Goes well beyond annotations: discloses that the first store claims the namespace and returns a one-time token, that the token cannot be recovered, that metadata is stored in the clear, and that conditional writes return 'precondition_failed' instead of clobbering. 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 long but every sentence carries critical information. It is front-loaded with the core purpose and security model, then token handling, concurrency, and cost. The structure is logical, though a slightly tighter wording could be possible without losing 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 complex tool with 9 parameters, an output schema, and annotations, the description covers essential aspects: security, token lifecycle, concurrency safety, cost, and payment alternatives. It also mentions the precondition_failed status. The output format is presumably in the output schema, so not needed here.

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

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

Schema coverage is 100%, but the description adds significant context: explains the one-time nature of namespace_token, the compare-and-swap semantics of if_match, the create-only behavior of if_absent, and the credit_token payment path. This adds value beyond the schema.

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

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

The description clearly states the tool stores client-side encrypted data, explains the security model (no key, never sees plaintext), and distinguishes it from other vault operations like retrieve/delete. It also notes what is stored in the clear, making the scope precise.

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

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

Provides clear context for when to use conditional writes (if_match/if_absent) and payment options (credits_trial, credit_token). It implicitly distinguishes from other vault tools by describing the store action, but does not explicitly name alternatives or state when not to use this tool.

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

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

The description adds substantial behavioral caveats that annotations alone cannot convey: 'status':'ok' is not an endorsement, a first observation makes empty drift meaningless, prior_criticals remains the truthful signal after a baseline swaps, unreachable is inconclusive, and null price_usd means no conversion occurred. These do not contradict readOnlyHint/idempotentHint; they enrich the safety profile.

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 long but every section earns its place: the when-to-use rule is front-loaded, followed by the core mechanism, then the caveats most likely to prevent a mistaken payment. It uses clear emphasis markers (IMPORTANT, ALWAYS) to prioritize the highest-risk messages.

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 paid verification tool with an output schema, the description covers the necessary interpretation of statuses and fields, failure semantics, pricing, and payment fallbacks. There is no missing operational context an agent would need to decide whether to call it or act on its result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic guidance beyond field descriptions: expect should carry 'what the listing claimed', method should be the one you intend to pay with, and credit_token is explicitly an alternative balance that avoids an x402 payment. This lifts it above baseline without needing to repeat schema details.

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

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

The opening sentence names a specific action ('Call this BEFORE authorising payment') tied to a clear resource (an x402 endpoint not written by the caller), and the second sentence defines the mechanism ('fetches ... live payment challenge and compares it against every observation previously made'). This is precise and naturally distinguishes it from unrelated siblings like meetings_* or vault_*.

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

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

It states exactly when to invoke ('BEFORE authorising payment to any x402 endpoint you did not write yourself'), tells the agent to prefer live charges over directory listings, and routes users without funding to credits_trial. It also tells the caller which HTTP method to use ('Use the method you intend to pay for') and what conditions should prevent payment ('stop and confirm out of band').

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