image-ocr

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

Beyond the raw annotations, it discloses that credits remain pending, are not spendable until confirmation, the payment environment is Stripe TEST, and a caller key is required. These are precisely the behavioral facts an agent needs before invoking 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?

Two compact sentences deliver the essence: endpoint, stage of flow, pending/spendable caveat, and auth requirement. No filler or redundant restatement.

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

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

Given a single well-documented parameter, no output schema, and low overall complexity, the description is complete. It covers what happens, what does not happen, what is required, and what to do next.

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 pack_id parameter is already documented. The description adds no further parameter-level detail, which is acceptable but does not elevate the score above the baseline.

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

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

The description states a specific action—creating a Stripe TEST PaymentIntent for a credit pack—and names the endpoint. It also distinguishes this from confirm_credits by clarifying that this step only produces an intent and does not grant credits.

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 clearly frames checkout_credits as the first stage of a two-step flow and references confirm_credits as the required follow-up. It does not explicitly enumerate when not to use it, but the context is clear enough for an agent to route correctly.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description adds meaningful behavioral context: confirming is the point where credits become granted/spendable and it appends credit.purchase with credits_added. This goes beyond the annotations and clarifies the side effect.

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

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

The description is compact and front-loaded, stating the action, test card, endpoint, side effect, and TEST-only restriction in three short sentences. Every sentence earns its place with no filler.

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

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

For a one-parameter, no-output-schema tool, the description is complete: it says what to do, what source the ID comes from, what the effect is, and that it is TEST only. An agent has enough information to select and invoke it correctly.

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

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

Schema description coverage is 100% and the single parameter is already well documented as the PaymentIntent id from checkout_credits. The description adds no new parameter-level detail, but it also does not need to, since the schema carries the full semantic 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?

The description uses a specific verb ('Confirm') and resource ('a TEST PaymentIntent' for credits), and gives the endpoint. It clearly states the tool is TEST-only and explains the effect (credits become granted/spendable), which distinguishes it from checkout_credits and credit_balance.

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

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

The description establishes clear context: this confirms a PaymentIntent from checkout_credits and is TEST only. It implicitly tells the agent when to use it, though it does not explicitly name alternatives or give when-not-to-use exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'Derived' nature and the GET endpoint, which is useful, but it does not disclose the return format or any edge cases. This meets the baseline for a simple read 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?

A single, front-loaded sentence with no wasted words. It conveys the core purpose immediately and includes the endpoint for clarity.

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

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

For a zero-parameter read tool with annotations covering safety, the description is adequate. It could specify the unit of the balance or that it is the caller's current balance, but those are minor omissions. No output schema exists, but the description does not need to explain return values for such a straightforward operation.

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

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

The tool has zero parameters and schema description coverage is 100%, so the baseline of 4 applies. The description correctly avoids adding parameter details because there are none.

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 'Derived' and resource 'prepaid balance for this caller_id', and it is clearly distinct from siblings like checkout_credits or credit_events which involve actions or history. The endpoint reference adds precision.

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?

No guidance is given on when to use this tool versus alternatives such as quote_credits or credit_events. For a simple balance query the intended usage is obvious, but the description does not explicitly state it or mention any exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly indicates an append-only, read-only nature. It adds context by mentioning 'append-only' and the optional balance snapshot, which is beyond the annotations. 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 a single sentence with structured event names and the endpoint in parentheses. It is concise and front-loads the core concept (append-only ledger events) before listing specifics. No fluff, but could be slightly more explicit about the action.

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, no-parameter tool, the description provides a solid list of event types and confirms the append-only nature. However, it doesn't describe the output format (e.g., fields like timestamp, amount, type) or how pagination works, which could be useful. Given the output schema is absent, complete guidance is missing, but the tool is simple enough that this is acceptable.

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

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

Schema coverage is 100% with zero parameters, and the description mentions caller_id and the available event types, providing context that is not visible from the empty schema. Since there are no parameters to document, the baseline is 4, and the description effectively fills the gap.

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 specific event types (credit.grant, credit.purchase, etc.) and the endpoint, but it doesn't clearly state the primary action ('retrieve' or 'list'). It lists what the events are, but the verb is implicit from the endpoint, which may not be immediately obvious to an agent.

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 hints at events for this caller_id but doesn't explain when to use this tool versus credit_balance or other credit-related siblings. It lacks explicit conditions or alternatives, leaving the agent to infer that this is for listing events rather than checking current balance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds value by specifying the HTTP method (GET), the auth requirement (No key), and the response fields (billing test/gated and runner_ready). This is beyond the annotations and provides useful behavioral context without 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 a single sentence that packs essential information: the endpoint, its purpose, the auth requirement, and the key response fields. It is front-loaded with 'Public readiness' and leaves no waste. Every part earns its place, making it highly concise 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?

For a zero-parameter, read-only health check with annotations covering safety, the description is complete. It provides the HTTP method, the path, the auth context, and the response shape. An agent has everything needed to call it correctly without missing information.

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

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

The tool has zero parameters, so the schema already documents everything (vacuously). The description doesn't need to add parameter details; it correctly focuses on the endpoint and response. With no parameters, this is a baseline of 4, and the description appropriately avoids redundant parameter information.

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 a health/readiness check for the /health endpoint, specifying it returns billing status and runner_ready. It distinguishes itself from the sibling tools, which are all credit-related, by describing a public readiness endpoint. The verb is implicit (GET) but the resource and intent are clear.

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 states 'Public readiness' and 'No key,' indicating this is a public health check with no authentication. However, it does not explicitly provide when-to-use vs. alternative tools or mention exclusions. It gives enough context to infer its purpose but lacks explicit 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 indicate readOnlyHint=false and destructiveHint=false, but the description adds important behavioral context: the secret is returned only once, the first issue grants 1 free credit, and the credit.grant reason is first_key. This goes beyond the annotations and helps the agent understand side effects and one-time 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?

The description is compact and information-dense, covering endpoint, install flow, auth, free credit, and cost guidance in a few sentences. It is front-loaded with the core action. Slightly dense but each 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 zero parameters and no output schema, the description covers the essential context: what the tool does, when to use it, auth details, one-time secret behavior, and credit implications. It could mention the response format, but the one-time secret note partially covers that. Overall, complete enough 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining the endpoint, authentication, and the one-time secret return. With 0 params, baseline is 4, and the description adds relevant context about the operation.

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's purpose: mint a caller key via POST /keys, and it distinguishes this from sibling tools like revoke_key and rotate_key. The title adds context about OCR/vision text, but the description itself is specific about the action and resource.

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 provides explicit guidance on when to use this tool: at bot install start, with the sole advertised entry at the given URL. It also mentions authentication preferences (Bearer vs X-API-Key alias) and a prerequisite to quote cost with quote_credits before ocr_extract. It doesn't explicitly name alternatives, but the context is clear.

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

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

Annotations already denote readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context: these are TEST packs, the operation is a GET, and credits are not granted by checkout alone—this last point cautions against a plausible misuse.

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 brief sentences, each earning its place: the first identifies the resource and endpoint, the second gives the critical lifecycle caveat. No fluff, no repetition of schema or annotations.

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

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

For a zero-parameter list tool with readOnly annotations, this is nearly complete: it covers the test nature, the endpoint, and the related checkout/confirm flow. The only minor gap is that the pack types (image ocr, ocr text, vision text) appear in the title but not the description, which could help agents interpret results.

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

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

The tool has zero parameters and the empty schema is 100% described. With no parameters, the baseline is 4 and the description need not add parameter detail—there is nothing to document.

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 'Prepaid TEST packs (GET /credits/packs)', specifying the verb 'list' and the resource 'credit packs'. It also differentiates from sibling write tools by noting the checkout/confirm flow, even though it doesn't explicitly name an alternative read tool.

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 lifecycle note ('checkout_credits is intent only; credits grant after confirm_credits') implies this is the read-only step before checkout/confirm, giving useful context. However, it doesn't explicitly state when to use this tool versus alternatives, such as 'list packs before initiating checkout'.

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

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

The description is behaviorally rich, warning that a successful OCR call debits 1 credit, exposing credits_burned and credits_remaining, and describing error and retry semantics. However, it directly contradicts the readOnlyHint=true annotation by describing a state-changing side effect (credit.debit reason=ocr_success), which forces a score of 1 per the rubric.

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 operation and packs setup, auth, cost, success, and error handling into a dense block. It is efficient overall, though the single run-on format and slightly redundant retryable/next phrasing keep it from a top score.

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

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

Given no output schema, the description covers the essential lifecycle: install, auth, quoting, credit cost, response fields, and error mapping. The main omission is the shape of the successful OCR payload beyond the credit fields, but the golden URL and llms.txt reference partially cover verification.

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 sole url parameter already documents the absolute http(s) requirement. The description repeats the golden URL but adds no significant new parameter semantics beyond providing a test value, so it earns the baseline 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 opens with 'Image OCR (POST /ocr)' and the title states 'OCR image URL to plain text', giving a specific verb, resource, and transformation. This cleanly differentiates it from the sibling credit and key-management 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 concrete preconditions: prefer Authorization Bearer over X-API-Key, quote first with quote_credits before the OCR call, and handle 401/402/retryable failures via next. It provides clear context and workflow, though it does not explicitly name an alternative OCR tool or state when not to use it; since the siblings are all non-OCR operations, this is adequate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it's a dry-run that does not debit, and it returns would_succeed, which implies the tool can predict success without executing. This goes beyond the annotations by explaining the non-mutating quote 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 sentences with no waste. The first sentence states the core purpose and endpoint, the second lists the return values. All information is front-loaded and relevant.

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

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

For a simple read-only quote tool with one optional parameter and no output schema, the description is nearly complete. It covers the operation, the non-debit behavior, and the key return fields. It could mention that 'op' accepts other values beyond ocr, but the schema already documents that. The absence of an output schema is compensated by listing the return fields in the description.

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 single parameter 'op' is already documented in the schema. The description adds the default value ('Defaults to ocr') and shows an example value in the endpoint path, which is helpful but not extensive. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: a dry-run cost quote for an operation without debiting credits. It names the specific endpoint (GET /credits/quote?op=ocr) and the key outputs (cost, balance, would_succeed), distinguishing it from actual debit operations like checkout_credits or confirm_credits.

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 it: when you need to check cost before performing an operation, without debiting. It doesn't explicitly name alternatives or exclusions, but the 'dry-run' and 'without debit' phrasing clearly separates it from sibling tools that perform actual credit transactions. The sibling context (checkout_credits, confirm_credits) reinforces this 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 declare destructiveHint=true, and the description adds meaningful behavioral context: the same id is revoked, the old secret returns 401 invalid_api_key, and X-API-Key is an alias. It also explicitly states 'No ops file-edit,' which is a useful exclusion. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded with the core action ('Invalidate the presented secret'). The additional details about 401 behavior and header preference are valuable and concise. The title's trailing 'image ocr, ocr text, vision text' is noise, but the description itself is 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?

For a zero-parameter destructive tool, the description covers the essential context: what happens, the error code, and the authentication mechanism. It lacks an explicit warning about irreversibility, but the destructiveHint annotation and 'Invalidate' convey that. The 'No ops file-edit' note adds clarity about scope.

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 has zero parameters, so the description doesn't need to explain parameters. The description instead clarifies that the secret is 'presented' via the request context (Authorization header or X-API-Key), which is essential for an agent to understand how the tool knows which key to revoke. This compensates for the empty 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 invalidates the presented secret and references the POST /keys/revoke endpoint. It distinguishes itself from siblings by noting it revokes the same id, while rotate_key likely issues a new secret. However, the title's trailing 'image ocr, ocr text, vision text' is confusing and unrelated to the described 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?

The description provides explicit guidance on authentication preference: 'Prefer Authorization: Bearer; X-API-Key is an alias only.' It also clarifies the effect (old secret fails 401) and notes 'No ops file-edit,' which helps an agent understand what this tool does not do. It does not explicitly name alternatives like rotate_key, but the context is sufficient.

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 sparse annotations by disclosing the key behavioral consequences: old secret returns 401 invalid_api_key, new secret is shown only once, and no ops file-edit occurs. This is exactly the kind of side-effect clarity an agent needs.

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

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

Four short, information-dense sentences. The main action is front-loaded, and every sentence adds distinct value—behavior, return behavior, auth preference, and operational caveat—with no filler.

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

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

For a zero-parameter tool with no output schema and minimal annotations, the description is remarkably complete. It tells the agent what happens, what the response contains, how the old credential behaves, and how to authenticate.

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 no parameters, so the baseline is 4. The description still adds useful context about what is preserved (id/caller_id and credits), which helps an agent reason about the operation's semantics even without inputs.

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

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

States a specific action ('Replace the presented secret') with the resource and endpoint (POST /keys/rotate). It is clearly differentiated from siblings like issue_key, revoke_key, and verify_key, and the title's odd suffix does not undermine the description.

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

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

Provides clear operational context: same id/caller_id and credits are preserved, and the new secret is returned only once. It also gives concrete auth guidance (prefer Bearer; X-API-Key is alias only), though it does not explicitly name when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral detail beyond annotations: it does not echo the secret and X-API-Key is only an alias. This is valuable context for an agent deciding whether the call is safe.

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 short, purposeful clauses: what it confirms, which credentials are accepted, and the no-echo guarantee. Every sentence earns its place and the core action is front-loaded.

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

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

For a zero-parameter read-only verification call, the description is complete: it states the operation, the accepted credential forms, the alias limitation, and a key safety behavior. No invocation-critical information 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 is empty, so there are no parameters whose semantics need clarification; the baseline for a zero-parameter tool is 4. The description adds relevant auth context rather than parameter detail, which 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 uses a specific verb ('Confirm') and resource ('key'), and further specifies the API key header and Authorization form with the exact endpoint. This clearly distinguishes verification from the key lifecycle siblings like issue_key, revoke_key, and rotate_key.

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

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

The intended use is implied: call this to confirm a key is valid rather than to create or revoke one. However, the description does not explicitly name alternatives or state when to prefer this tool over sibling key-management tools; the X-API-Key alias caveat helps prevent misuse but is not full routing guidance.

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