feed-digest

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

Annotations only state readOnlyHint=false and destructiveHint=false; the description adds crucial behavioral detail: it's an 'intent only' call, returns credits_pending, does not grant spendable credits until confirm_credits succeeds, requires a caller key, and operates with 'No live Stripe' (test mode). This goes well beyond the annotations and helps an agent set expectations.

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 concise sentences that front-load the core purpose and endpoint, then immediately convey key behavioral caveats (intent-only, pending status, confirmation requirement, auth, test mode). Every sentence contributes unique information; there is 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 single-parameter tool with no output schema, the description covers the return value (credits_pending), the side-effect (credits not granted), the auth requirement, and the test environment. This is nearly complete; it could optionally mention error cases or how the returned pending credit relates to confirm_credits, but those are minor for an agent to infer.

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 only parameter, pack_id, is already documented with a clear source ('from list_credit_packs') and example. The description adds no extra meaning to the parameter, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('checkout' intent) and resource ('pack'), names the endpoint (POST /credits/checkout), and explicitly distinguishes this from confirm_credits by noting credits are not granted until that sibling succeeds. This leaves no ambiguity about what the tool does.

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

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

The description clarifies the intended flow: checkout first, then confirm_credits, and notes the prerequisite of a caller key. It does not name other siblings (e.g., quote_credits, list_credit_packs) as alternatives, but the step-by-step context is clear enough for an agent to know when to invoke 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?

Beyond the annotations, the description adds the key side effect: credits 'become granted/spendable' and an event is appended to credit.purchase with credits_added. This meaningfully clarifies the write behavior without contradicting readOnlyHint=false or destructiveHint=false.

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 itself is tight and front-loaded: endpoint, effect, then constraints. However, the tool title is noisy and includes unrelated terms like 'rss digest, atom feed, feed items,' which detracts from an otherwise clean definition.

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

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

For a single-parameter TEST-only confirmation tool, the description explains the purpose, the side effect, the source of the parameter, and the synthetic environment. It does not describe response shape or error behavior, but the operation is simple and the core invocation context is covered.

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 explaining that the parameter is synthetic ('Synthetic pi_test_… until LAS-212'), reinforcing the TEST-only usage beyond the schema's simple 'PaymentIntent id' wording.

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

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

The description states a specific verb and resource: 'Confirm a TEST checkout intent (POST /credits/confirm).' It also distinguishes this from the sibling checkout_credits by noting the PaymentIntent comes from that flow. The action and domain are unambiguous.

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

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

The description clearly marks the tool as TEST only and references synthetic pi_test_ IDs, which tells an agent not to use it for production. It implies sequencing after checkout_credits via the parameter description, though it does not explicitly name alternatives or state when not to use it beyond the TEST-only constraint.

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 useful context by noting the balance is 'derived' and scoped to 'this caller_id', but it does not describe response format, error behavior, or any rate-limit implications.

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 compact sentence, front-loads the core meaning, and includes the endpoint without fluff. Every part contributes to understanding 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 parameterless, read-only balance lookup with no output schema, the description is mostly complete: it names the resource, the scoping, and the operation. A minor gap is that it does not indicate the return format or units of the balance.

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 coverage is 100%, so there are no parameter details to document. The mention of caller_id provides implicit context that the balance is tied to the authenticated caller, which is sufficient.

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 resource as the derived prepaid balance for the caller_id and gives the endpoint GET /credits/balance. However, it lacks an explicit verb and does not distinguish itself from siblings like list_credit_packs or credit_events; the title adds confusing unrelated terms like 'rss digest' and 'atom feed'.

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 about when to use this tool versus alternatives such as quote_credits, checkout_credits, or credit_events. The description states what the tool returns but provides no conditions, exclusions, or context for choosing 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?

With readOnlyHint true and destructiveHint false, the annotations already establish the safe-read profile; the description adds that events are append-only, scoped to the caller, and that debit reason digest_success follows a successful digest. It does not describe the response format or clarify the rss/atom/feed item aspect from the title.

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 core purpose and one important event-trigger fact without filler. The second sentence is dense and somewhat cryptic, but it earns its place by explaining when the digest_success debit event is created.

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 tool with annotations, the endpoint and event semantics provide a usable picture. However, there is no output schema and the title advertises rss/atom/feed items that the description never addresses, leaving the returned shape ambiguous.

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 no parameters, and schema coverage is effectively 100% via an empty input schema, so there are no parameter semantics to document. The description's caller_id reference appears to be authentication context, not an input parameter, and no additional parameter guidance is needed.

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 identifies the resource (credit events for the caller_id) and the exact endpoint (GET /credits/events), so an agent can see this is a read-only ledger listing rather than a balance or purchase tool. It does not explicitly contrast itself with sibling tools like credit_balance or digest_feed, and the title's mention of rss/atom/feed items is not integrated.

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 the tool is for viewing caller-scoped credit ledger events and adds a relevant event trigger (digest_success after a successful digest), but it never states when to prefer this tool over credit_balance or digest_feed. There are no explicit when-not-to-use or alternative routing instructions.

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

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

Beyond the readOnly/destructive hints, the description discloses credit debits, the free first credit, credits_burned/credits_remaining in success bodies, and a detailed error contract including 401/402 handling and retry semantics. This is substantial behavioral transparency with no contradiction; the billing side effect is clearly disclosed.

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

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

The definition is front-loaded with the core action, but the rest is a dense run-on paragraph mixing installation, authentication, credits, and error handling. Some details, like the golden URL, repeat the schema, and the lack of structure makes the important operational rules harder to scan.

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 API with no output schema, it thoroughly covers auth, cost, and failure modes. However, it never clearly specifies what the success body contains beyond credits_burned and credits_remaining, leaving the actual digest/feed response structure implicit.

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

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

The input schema already fully documents the url parameter, including the public http(s) RSS/Atom constraint and the golden proof URL. The description mostly restates this and adds endpoint context, so the baseline score of 3 applies.

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

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

The description opens with a concrete action and resource: 'Fetch a public RSS or Atom feed (POST /digest).' The title reinforces the resource, and no sibling tool performs feed digestion, so an agent can distinguish it immediately 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?

It gives practical invocation guidance: preferred auth scheme, the sole install path, a golden test URL, and a prerequisite workflow with quote_credits. It does not explicitly compare against alternative feed tools, but no sibling is a real alternative; the quote-first instruction is the relevant 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 mark this as read-only and non-destructive. The description adds valuable behavioral context by stating the endpoint is public and requires no key, and by exposing the possible billing states (test|gated) and runner_ready field.

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 sentence conveys the endpoint, publicness, key requirement, and response fields with no filler. The information is front-loaded and every clause adds value.

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 no-parameter health check, the description covers the essential invocation details and expected response content. It does not mention response format, but the tool's simplicity makes that an acceptable omission.

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

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

The tool has zero parameters, so the input schema carries no burden. The description still clarifies that no key is needed, which effectively documents the parameter-less invocation. This is a reasonable baseline for a no-parameter tool.

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 this is a public readiness check via GET /health and lists the key fields (billing, runner_ready). It is specific and actionable, though the title is somewhat noisy with unrelated terms like rss digest and atom feed.

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 usage context: use this to check public readiness without authentication. However, it does not explicitly contrast with sibling tools like digest_feed or verify_key, leaving some ambiguity about when this is preferred over 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?

Beyond the minimal annotations, the description discloses important non-obvious behaviors: the secret fdg_... is returned only once, the first issue grants a free credit with reason=first_key, Authorization: Bearer is preferred, and X-API-Key is an alias. This goes well beyond the annotated readOnly/destructive hints.

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, entry-point flow, one-time secret, auth preference, credit grant, and cost-query reminder. The key action is front-loaded and the remaining details are densely packed without fluff.

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

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

For a zero-parameter tool with no output schema, the description is sufficiently complete: it identifies the endpoint, authentication method, one-time secret behavior, free-credit consequence, and the expected next step (quote_credits before digest_feed). An agent has what it needs to invoke the tool correctly.

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

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

The schema has zero parameters and 100% description coverage, so the baseline is 4. The description adds relevant operational context (endpoint, auth, credit consequences) even though there are no parameters 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 opens with a specific verb and resource, 'Mint a caller key (POST /keys)', which names exactly what the tool does and the HTTP endpoint. This clearly distinguishes it from sibling key lifecycle tools like verify_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?

It gives clear contextual usage: the key is minted at bot install, starting from the llms.txt entry, and cost should be quoted with quote_credits before digest_feed. It does not explicitly state when not to use this tool versus its lifecycle siblings, so it falls short of a 5.

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

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 context that these are 'TEST' packs and that credits are only granted after confirm_credits, which is useful for understanding the lifecycle. It does not describe the return format or pagination behavior, but for a simple read-only list, the added context is adequate without being rich.

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

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

The description is two concise sentences with no wasted words. The primary resource and endpoint are front-loaded, followed by a crucial clarification about the credit flow. Every sentence earns its place, achieving optimal brevity.

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 no-parameter, read-only list tool with annotations covering safety, the description provides the essential context: what is listed (prepaid test packs) and how it relates to the checkout/confirm flow. It does not describe the output structure, but since there is no output schema and the tool is a simple list, an agent can infer it returns the packs. Overall, it is sufficiently complete, though a brief note on the response format would push it to a 5.

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 schema coverage is effectively 100% (no parameters to document). Per the rubric, a baseline of 4 is appropriate. The description adds no parameter-specific detail because there are none, but it correctly does not invent any. It does mention the endpoint, which is not strictly required given 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 identifies the tool as retrieving 'Prepaid TEST packs' via the endpoint 'GET /credits/packs', which is a specific verb-resource pair. It distinguishes itself from related tools by clarifying the credit lifecycle ('checkout_credits is intent only; credits grant after confirm_credits'). However, it does not explicitly contrast with a sibling that might perform a similar listing, and the title's broader scope ('rss digest, atom feed, feed items') could introduce ambiguity, so it is not a full 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 provides context about when this tool fits in the credit flow (checkout vs. confirm), implying it should be used to inspect available prepaid packs before checkout. It does not explicitly state when NOT to use it or name an alternative for similar functionality, leaving the guidance implicit 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=true and destructiveHint=false, and the description reinforces this with 'without debit.' It also adds useful behavioral detail beyond annotations: the endpoint shape and the fact that it returns cost, balance, and would_succeed.

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 extremely concise: one sentence conveys purpose, endpoint, debit behavior, and return fields. Every phrase earns its place and the most important constraints are 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 low-complexity tool with one optional parameter and no output schema, mentioning the return fields is valuable and mostly sufficient. It is slightly incomplete because possible op values beyond 'digest' are not enumerated, even though the title hints at rss digest, atom feed, and feed items.

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 for the single parameter is 100%: 'op' is already described as the operation to quote with a default of digest. The description adds only an example URL and does not significantly 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 states a specific action: dry-run cost for an operation without debiting. It names the resource/endpoint and the return fields, and the 'without debit' framing clearly distinguishes it from debit-related siblings like checkout_credits and 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?

It is clear you use this tool when you want a no-debit cost estimate before performing an operation. However, it does not explicitly name the alternative tools that would actually perform the debit, so it stops short of explicit when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true, and the description goes beyond that by specifying the concrete consequence: the old secret fails with 401 invalid_api_key and the same id is revoked. It also discloses a scope constraint with 'No ops file-edit', adding useful behavioral detail beyond the annotation flags.

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 concise sentences with no filler. The core action and consequence are front-loaded, and the auth guidance and side-effect note each earn their 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 zero-parameter, destructive revocation tool, the description covers the action, the mechanism, the auth method, and the post-revocation behavior. With annotations already marking destructiveness, nothing essential is missing for an agent to invoke it correctly.

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

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

The input schema has no parameters, so there are no parameter semantics to document. The description nevertheless clarifies that the secret is presented via HTTP auth rather than as a parameter, noting the Bearer preference and X-API-Key alias.

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: 'Invalidate the presented secret (POST /keys/revoke)', which clearly states the action and endpoint. It further defines the effect (same id revoked, old secret fails with 401), distinguishing it from siblings like rotate_key or verify_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 description provides clear invocation context: the secret is presented via the request, and Authorization: Bearer is preferred over X-API-Key. However, it does not explicitly state when to use revoke_key versus siblings such as rotate_key or verify_key, leaving the choice partly implied.

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 signal that this is neither read-only nor destructive, but the description goes beyond them by disclosing that the new secret is returned once, that the old secret will fail with 401 invalid_api_key, that identity and credits are unchanged, and that the Bearer header is preferred. It also includes the operational caveat about not editing ops files. No contradiction with the 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 six short sentences, each carrying a distinct piece of information: the operation, identity/credit preservation, one-time secret output, old-secret failure behavior, auth preference, and an ops limitation. It is front-loaded with the primary verb and resource and contains 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 no-parameter, no-output-schema tool, the description covers purpose, side effects, output, error behavior, and authentication well. The main gaps are the absence of explicit routing guidance relative to issue_key/revoke_key and the unexplained connection to the feed/digest/atom terms present in the tool title.

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 schema parameters, so the baseline is 4; the description still adds meaning by explaining how the 'presented secret' is supplied via Authorization: Bearer and that X-API-Key is merely an alias. This is effective parameter-level guidance even though the input schema is empty.

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 concrete action, 'Replace the presented secret (POST /keys/rotate)', and immediately clarifies that the same id/caller_id and credits are preserved. This makes the operation unambiguous and distinguishes it from siblings such as issue_key or revoke_key without needing to inspect their schemas. The slightly noisy title is outweighed by the clear, specific body text.

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

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

The description clearly establishes the context: use this tool to rotate the presented secret while keeping identity and credits intact, and it adds operational guidance about authentication ('Prefer Authorization: Bearer; X-API-Key is an alias only') and an explicit boundary ('No ops file-edit'). It does not explicitly name sibling alternatives or provide a 'use this instead of X when...' statement, so the alternative routing is implied rather than fully 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 establish the read-only, non-destructive nature, and the description adds meaningful behavioral detail by noting that X-API-Key is only an alias and that the tool does not echo the secret. This goes beyond the annotation coverage without contradicting it.

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

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

Three short sentences front-load the core purpose and immediately add the alias and security caveat. 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 zero-parameter, read-only verification tool, the description covers purpose, authentication header options, and the non-echo behavior. It does not state the response/return semantics, but the endpoint and verb make the validity outcome fairly inferable.

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?

With zero parameters and 100% schema coverage, there is no parameter documentation gap. The description adds value by specifying where the key is sourced (header rather than JSON body), which is useful given 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 operation as confirming the caller key via FEED_DIGEST_API_KEY or Authorization: Bearer, with the endpoint GET /keys/verify. The verb-resource pair is specific, though it does not explicitly contrast with sibling key-management tools or explain why the title also lists rss digest/atom feed/feed items.

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 practical context: use this to confirm a caller key and present it via one of the named header forms. It does not explicitly say when to prefer this over issue_key/revoke_key/rotate_key or state when not to use it.

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