shelf-smoke — url smoke / headless QA

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

Annotations already indicate this is not read-only and not destructive. The description adds valuable behavioral context: it's a TEST PaymentIntent, it only creates a pending state, credits are not spendable until confirm_credits, and it requires a caller key. This goes beyond the annotations and helps the agent understand side effects and prerequisites.

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

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

Three sentences, each earning its place: what it does, the critical pending-state caveat, and the auth requirement. Front-loaded with the core action and endpoint.

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 essential context: the endpoint, the test nature, the pending state, the follow-up tool, and the auth requirement. It doesn't describe the return format, but with no output schema and a simple intent-only operation, this is a minor 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 coverage is 100% and the single parameter pack_id is already described as 'Pack id from list_credit_packs (e.g. pack_10).' The description doesn't add much beyond the schema, but the schema is sufficient. 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 clearly states the specific action (Stripe TEST PaymentIntent for a pack), the endpoint (POST /credits/checkout), and the key behavior (intent only, credits not granted until confirm_credits). It distinguishes itself from confirm_credits by explicitly noting the follow-up step.

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

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

The description implies when to use this tool: to initiate a credit pack purchase, with the explicit note that credits are not granted until confirm_credits succeeds. It names the sibling confirm_credits as the follow-up, but doesn't explicitly state when not to use it or compare with quote_credits. The context is clear enough for an agent to select 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 only indicate a non-read-only, non-destructive operation. The description adds meaningful behavior: it appends a credit.purchase record and makes credits spendable, and it restricts use to test cards/environment. This is valuable context 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?

Two sentences, front-loaded with the action and test card, followed by the side effect and TEST-only constraint. 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?

For a single-parameter mutation tool with no output schema, the description covers purpose, side effect, and environment restriction. It doesn't mention failure behavior or auth, but those are less critical for a simple test confirmation tool, and sibling workflow is implied by the param 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 description coverage is 100%, and the parameter is clearly documented as a PaymentIntent id from checkout_credits. The tool description does not add additional parameter-level detail, so 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?

The description states a specific action: confirming a TEST PaymentIntent with Stripe test card pm_card_visa, and identifies the POST /credits/confirm endpoint. It also explains the resulting side effect (credits become spendable, credit.purchase appended), which distinguishes it from lookup tools like credit_balance or quote_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 gives clear context: this is the point where credits are granted, and it explicitly constrains use to TEST only. It does not name sibling tools like checkout_credits directly, but the parameter schema references 'from checkout_credits,' so the workflow is implied. A more explicit alternative comparison would push this to 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 annotations declare readOnlyHint=true and destructiveHint=false, indicating this is a safe read. The description adds that the balance is 'derived' and is a GET request, but does not detail what 'derived' means (e.g., computed on the fly vs. stored) or any caching or rate-limit behavior. With annotations covering the safety profile, the description adds minimal extra context, resulting in a mid-range score.

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 is extremely concise and contains no fluff. It immediately states the tool's purpose and provides the HTTP method and endpoint. Every word 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 tool has no parameters, no output schema, and the annotations already establish read-only safety, the description is close to complete. However, it does not describe the return format or any specific behavior (e.g., whether it requires authentication). The title hints 'url smoke, headless qa', which might indicate it's used for testing, but the description does not clarify the expected output or use case fully. A 3 is fair because some context 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 tool has zero parameters, so there is no schema to cover in the description. The description mentions 'this caller_id', implying that the caller_id is somehow provided (likely via context or implicit auth), but this is not further explained. Since no parameter semantics are needed, a baseline of 4 is appropriate, as the description provides the key contextual information that the balance is for the caller.

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 retrieves a derived prepaid balance for a given caller_id, and identifies it as a GET request to a specific endpoint. It distinguishes the resource (credit balance) from siblings like credit_events or quote_credits, making its purpose 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 provides no guidance on when to use this tool versus alternatives, such as checkout_credits or quote_credits. While the endpoint is implied, the description is terse and does not explain under what circumstances an agent should call this endpoint (e.g., to check balance before purchase). The context of 'url smoke, headless qa' hints at testing, but there is no explicit 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=true and destructiveHint=false, so the description is not repeating that. It adds valuable context: 'Append-only' clarifies that events cannot be modified or deleted, and the caller_id scoping indicates the data is filtered by caller. It also lists event types, giving the agent a preview of what to expect. 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 a single, dense sentence that leads with the resource and action, then enumerates the event types. Every phrase earns its place, with no filler. It is appropriately sized for a zero-parameter read-only list.

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 list tool with annotations covering safety, the description is nearly complete. It tells the agent what events are returned and the scoping. However, it does not describe the response format (e.g., array, object) or any pagination/ordering behavior. Since there is no output schema, a brief mention of the response shape would improve completeness, but the current description is adequate for most use cases.

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 the schema trivially covers all (100%). The description does not need to explain parameter meaning. The mention of 'caller_id' in the description hints at the implicit context but there are no explicit parameters to document. Baseline for 0 params is 4, and the description adds no extra parameter-related info, which is acceptable.

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 resource (GET /credits/events), the verb (GET), the scope (caller_id), and the specific event types (credit.grant, credit.purchase, credit.debit, optional balance_snapshot). This distinguishes it from siblings like credit_balance (a single balance) or list_credit_packs (pack listings). The phrase 'Append-only Ledger events' adds a precise resource definition.

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 offers no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contrast with sibling tools. The title hints at 'url smoke, headless qa' but this is not in the description and provides only vague context. An agent must infer that this is the go-to for listing ledger events without any explicit routing.

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

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

Annotations already mark this as read-only and non-destructive. The description adds valuable traits beyond that: it is a public endpoint requiring no keychers, uses GET, and reports billing state plus runner_ready. This gives the agent a meaningful behavioral profile 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 a single compact sentence that front-loads the most important fact: this is a public readiness check. Every segment earns its place: endpoint, response fields, and authentication requirement.

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 health-check tool, the description is complete. It specifies the HTTP method, endpoint, public authentication status, and the key response fields (billing and runner_ready), so an agent has everything needed to invoke and interpret the call.

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 there is nothing for the description to explain. The baseline of 4 applies because the tool needs no input configuration and the schema fully reflects that.

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

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

The description names the exact resource and verb: 'GET /health', and defines the tool's purpose as a public readiness check. The 'No key' qualifier distinguishes it from sibling tools that likely require authentication, and the listed response fields clarify its scope.

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?

'Public readiness' plus 'No key' gives a clear context for when to call this tool: basic health checks without authentication. It does not explicitly compare against alternatives like smoke, so it misses the top score for explicit when-not/alternative routing, but the guidance is not merely 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?

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), it discloses the critical behavior that the secret is returned exactly once and that the first issue grants a free credit with reason 'first_key'. It also notes the authentication alias. It stops short of idempotency or rate-limit details, but the disclosed behavior is genuinely valuable.

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

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

Every sentence carries operational weight: the endpoint, the boot sequence, the authentication preference, the one-time secret, the free credit, and the cross-tool recommendation. The core action is front-loaded and there is no filler.

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

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

For a parameterless tool with no output schema, the description covers everything required to call it correctly: the HTTP method and path, authentication style, the nature of the response (one-time secret), the side effect (free credit), and the recommended prerequisite (quote_credits). Nothing essential 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?

With zero parameters, the baseline is 4. The description adds relevant non-parameter context (endpoint, auth method, one-time secret) that an agent needs, even though there is no schema to document. It does not repeat or contradict the schema, which is effectively 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 states the verb 'Mint' with the resource 'caller key' and the exact endpoint (POST /keys). It also names the specific use case ('url smoke, headless qa') which distinguishes it from siblings like verify_key or smoke. No ambiguity remains about what this tool does.

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

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

It explicitly says 'Prefer Authorization: Bearer; X-API-Key is an alias' for authentication, and instructs 'Quote cost with quote_credits before smoke' to route to a sibling tool. It also sets the sequence context with 'Bot install starts at GET https://shelf.kymac.co/llms.txt', making the usage conditions 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 declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context: the packs are TEST packs (not production) and the flow clarifies that listing does not grant credits. It goes beyond annotations without contradicting them, though it does not describe return format or pagination.

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 with no waste. The key information (test packs, endpoint, flow) is front-loaded. Every word earns its place, and the clarification about intent vs. confirmation is concise and meaningful.

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 parameters and no output schema, the description covers the essential purpose and flow. It mentions the test nature, which is critical for an agent to avoid misusing it as a production list. The only minor gap is the absence of any note about response structure, but for a simple list endpoint that is often unnecessary. The workflow explanation fills most gaps.

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 the baseline is 4. The description adds no parameter-specific info, but none is needed. The schema coverage is 100% trivially, and the description provides context about the resource's purpose.

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 resource ('Prepaid TEST packs') and the operation (GET /credits/packs), which is unambiguous. It also distinguishes itself from the checkout/confirm flow by noting that listing is not intent or confirmation. The verb 'list' is implied in the name and the endpoint, making it a specific, non-tautological purpose.

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

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

The description provides workflow context ('checkout_credits is intent only; credits grant after confirm_credits') which hints at when this list tool fits in the sequence, but it does not explicitly say when to use this tool versus siblings like quote_credits or credit_balance. The guidance is implicit, not a clear directive.

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 is a dry-run that does not debit, and it returns cost, balance, and would_succeed. This goes beyond the annotations and helps the agent understand the operation's side-effect-free nature.

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

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

Two sentences with no filler. The core behavior ('Dry-run cost for an op without debit') is front-loaded, and the return values are listed compactly. Every word 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-only quote tool with one optional parameter and no output schema, the description is nearly complete. It states the endpoint, the side-effect-free nature, and the return fields. The only minor gap is that it doesn't describe the format or structure of the returned cost/balance/would_succeed values, but that is not critical for a tool this simple.

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 schema already documents the 'op' parameter. The description mentions 'op=smoke' and says it defaults to smoke, which adds a small hint about the default value. However, it doesn't explain what other values might be valid or how the parameter affects the quote, so it adds only marginal 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 states a specific verb ('Dry-run cost'), a resource ('an op'), and the key behavior ('without debit'), and even names the endpoint (GET /credits/quote?op=smoke). It clearly distinguishes this from sibling tools like checkout_credits and confirm_credits by emphasizing that no debit occurs.

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 implies this is for checking cost and feasibility before committing to an operation, and the 'without debit' phrasing signals when to use it instead of checkout/confirm. It does not explicitly name alternatives or state when not to use it, but the context 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 already flag destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral details beyond that: the same ID is revoked, the old secret subsequently fails with 401 invalid_api_key, and there is an explicit auth preference. It also asserts a non-action ('No ops file-edit'), which is useful for understanding scope.

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

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

The description is three sentences with a clear logical order: action, effect, and usage caveats. Every sentence adds distinct information—endpoint, invalidation result, auth preference, and non-goal—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 no input parameters, no output schema, and strong destructive annotations, the description covers all essential aspects: the operation, its consequence, authentication method, and a scope boundary. Minor missing details such as idempotency or error handling could be added, but they are not critical given the simplicity.

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 in the schema, the baseline for this dimension is 4. The description's mention of 'the presented secret' and auth headers confirms that the key is obtained from the request context, but since there are no parameters to document, the description cannot add much more. The baseline 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 the specific verb 'Invalidate' and the resource 'the presented secret', plus the explicit HTTP endpoint 'POST /keys/revoke'. It further clarifies the effect ('old secret then fails 401 invalid_api_key'), which leaves no doubt about the tool's purpose even before considering sibling 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 implies usage through its action but provides no explicit guidance on when to choose revoke_key over alternatives like rotate_key or issue_key. It does supply auth-related usage advice ('Prefer Authorization: Bearer') and a negative boundary ('No ops file-edit'), but these do not directly distinguish this tool from its siblings.

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 discloses critical behavioral details: the new secret is returned only once and the old secret will fail with 401 after rotation. This adds real operational context. The description does not contradict the provided 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?

Four tightly packed sentences with no filler. The core behavior is front-loaded, and every sentence adds a distinct, useful fact: endpoint, identity/credit preservation, one-time return, old-key invalidation, auth preference, and the no-ops-file caveat.

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 mutation with no output schema, the description covers the essential operational contract: how to authenticate, what changes, what is returned once, and what happens to the old key. Minor gaps remain around idempotency or permission requirements, but nothing critical for a competent agent 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?

There are zero parameters, so the baseline is 4 and the description does not need to explain parameter meaning. It appropriately relies on the auth context rather than inventing 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 states a specific action ('Replace the presented secret'), names the endpoint, and clarifies the identity/credit impact. This clearly differentiates it from siblings like issue_key and revoke_key without needing to open their schemas.

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

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

It gives useful invocation guidance: prefer Bearer auth, X-API-Key is only an alias, and no ops file-edit. However, it does not explicitly explain when to choose rotate_key over issue_key or revoke_key, nor does it state any exclusions or prerequisites.

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 readOnlyHint and destructiveHint annotations, the description details credit debits (1 credit on ok:true), response fields (credits_burned, credits_remaining), error structures (code/message/retryable/next), and specific error cases (401, 402). This is extensive behavioral disclosure beyond the annotations, with 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 dense single paragraph that covers many edge cases, but it includes extraneous information like 'Install via GET https://shelf.kymac.co/llms.txt only' which is unrelated to the tool's operation. It lacks clear structure or sectioning, making it harder to scan, though every sentence carries some operational detail.

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 thoroughly covers response fields, error handling, credit mechanics, and retry logic. It is sufficiently complete for an agent to invoke the tool correctly and interpret results without additional documentation.

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 describes the url parameter with a clear definition and golden URL example (coverage 100%). The description reinforces the golden URL and adds the comparison concept, but does not introduce fundamentally new semantics beyond what the schema states.

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 runs a headless smoke test on a URL, referencing the POST /smoke endpoint and the golden URL comparison for ok true/false. It is distinct from sibling tools that manage credits or keys, and the verb-resource pairing is specific.

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 provides workflow guidance by advising to 'Quote first with quote_credits (no debit)' and explains credit debit conditions, which helps sequence usage. It does not explicitly name alternatives, but the context makes clear this is the tool for URL smoke testing, distinguishing it from credit/key operations.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already known. The description adds valuable behavioral details: the exact endpoint, the alias nature of X-API-Key, and explicitly states it does not echo the secret, which is a critical security behavior. This goes beyond the annotations to inform the agent about side-effect-free operation and data handling.

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

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

Two concise sentences, no filler. The most critical usage information (endpoint and credential formats) is front-loaded, and the security note is a valuable addition. Every word 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 zero-parameter tool with a trivial operation (key verification), the description is nearly complete. It covers input method, endpoint, security behavior, and alias clarification. Missing are details on the response format or success criteria, but the absence of an output schema and the simplicity of the task make this 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?

The tool has zero parameters, and schema coverage is 100% (empty schema). The description compensates by clarifying how the key is passed (via header or env var), which is not in the schema. This effectively explains the implicit input mechanism, which is essential for the agent to use the tool 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 clearly states the tool's purpose: verifying a caller's API key via a specific endpoint ('GET /keys/verify'). It explicitly mentions the accepted credential formats (SHELF_SMOKE_API_KEY or Authorization: Bearer), which is specific and distinguishes functionality. The mention that 'X-API-Key' is only an alias 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?

The description provides the endpoint and credential formats, implying correct usage. However, it lacks explicit guidance on when to use this tool versus alternatives; among siblings, 'smoke' might be a related check, but no comparison is made. No prerequisites or context for when this verification is appropriate is given.

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