VHGENGINE

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

Annotations include idempotentHint: true. The description adds detail: 'Idempotent on idempotency_key (replay does NOT grant twice),' and lists possible errors (unauthorized, invalid_request, idempotency_conflict, rate_limited). 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 relatively concise and front-loaded with the core purpose. It uses line breaks to separate key points (errors, behavior). Could be slightly more structured, but every sentence provides 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?

Given the tool has 4 parameters, an output schema, and complex conditional behavior, the description adequately covers the purpose, usage conditions, idempotency, and error scenarios. It does not explain api_key or detailed return structure, but the output schema likely handles the latter.

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 0%, so description must compensate. It provides the amount range (1-10000), explains admin_key condition, mentions idempotency_key behavior, and describes the return format. While api_key is not detailed, overall it adds significant 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 begins with 'Top up your credit balance (1-10000). Self-serve by default,' which clearly states the verb (top up), resource (credit balance), and scope (self-serve). This distinctly differentiates it from sibling tools like create_checkout or get_account.

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 explains when the tool requires an admin_key (when VHGENGINE_ADMIN_KEY is configured) and when it stays self-serve. It implies usage for adding credits but does not explicitly state alternatives, though no sibling tool serves a similar purpose.

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?

No annotations provided, so description carries full burden. Explains async credit behavior via webhook, lists return fields, and enumerates error types. Could add more about idempotency or rate limits, but covers core non-obvious behavior well.

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-sentence opening followed by bullet-style Args and Returns in clean prose. No fluff, front-loaded with purpose, efficient use of space.

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?

Output schema exists, so description needn't detail return format, but it still lists all return fields for clarity. Covers input, behavior, output, errors, and alternatives (add_credits). For a payment-initiation tool with async fulfillment, this is complete.

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 0%, so description must compensate. It explicitly explains 'pack' as 'a credits amount from pricing.credit_packs', notes optionality of success/cancel URLs, and clarifies api_key as 'spend scope'. This adds significant meaning beyond the schema's type definitions.

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

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

Description clearly states verb 'Get' and resource 'Stripe hosted-checkout link' for a 'credit pack'. Distinguishes from siblings by explicitly referencing 'add_credits' as an alternative. The first sentence captures the core action.

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 explicit context: 'You never touch a card' and instructs to hand URL to human. Includes conditional guidance 'payments_disabled (503; use add_credits)' which tells when not to use this tool and suggests an alternative. Also notes that credits come later via webhook.

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?

No annotations provided, so description carries full burden. It discloses that plaintext is returned once, admin scope requirement, delegation behavior, error types, and return fields. Fully transparent.

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?

Dense single paragraph with logical flow: purpose, requirement, delegation details, args, returns, errors. Could be slightly more concise but well-structured and information-dense.

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?

Covers input, behavior, errors, and return fields. Output schema not provided but description lists return fields. No gaps given tool complexity.

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 0%, but description explains each parameter: name (1-100), api_key (admin-scoped), scopes (subset of read|spend|admin; omit for full power), daily_credit_cap (credit limit; omit for uncapped). Adds meaning beyond 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?

Description specifies 'Mint a new named API key' with clear verb-resource, distinguishes from sibling revoke_key and list_keys. No ambiguity.

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?

States 'Requires admin scope' and explains delegation safety (WP-SCOPE) with optional scopes and daily_credit_cap, indicating when to use for sub-agent keys. Does not explicitly state when not to use, but 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?

Describes in detail the consequences: revokes all keys, deletes hooks, webhooks, etc., retains financial ledger, anonymizes outcomes. Also mentions errors and return format. Annotations already set destructiveHint, but the description adds extensive behavioral context.

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

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

The description is dense with information, front-loaded with the main action and caution. While somewhat lengthy, each sentence adds value. Could be slightly more structured, but overall efficient.

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

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

Given the destructive nature, the description covers prerequisites, preserved data, return value, and error scenarios. The output schema exists but the description already provides sufficient context for an agent to use the tool safely.

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 0%, but the description explains the confirm parameter's purpose and constraint (literal 'delete' guard). The api_key parameter is not mentioned, but it's optional and default null. The description adds significant value over the bare 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 permanently deletes an account. It distinguishes from sibling tools like delete_webhook or revoke_key by specifying 'delete this account' and including details unique to account deletion.

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

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

Explicitly tells the agent to pass confirm='delete' as a guard, to export data first via GET /v1/usage/export, and notes that a second call will 401. This provides clear when-to-use and 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 idempotentHint annotation, the description adds scope requirements, cost, return structure, and error conditions, though 'WP-M' is cryptic.

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?

Description is well-structured with clear sections for args, cost, returns, and errors; every sentence adds value without redundancy.

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

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

Given the simple tool with one optional parameter and an output schema, the description covers return format, errors, and scope adequately.

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 0% schema description coverage, the description compensates by explaining api_key's admin scope, adding meaning beyond the schema's type definition.

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 'Remove this account's webhook' with a specific verb and resource, and distinguishes from sibling tools like set_webhook, get_webhook.

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?

Description specifies 'Admin scope' and lists error conditions (unauthorized, forbidden, not_found) giving usage context, but does not explicitly mention when to avoid or suggest 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?

With no annotations, the description fully covers charging mechanisms, mode determinism, response shaping, progress streaming, error types, and safety checks like pre-flight gating. It transparently discloses behavioral traits 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 dense with useful info but slightly overwhelming in structure. It front-loads the core purpose and cost, but the technical details could be more scannable. Still, every sentence 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 tool with 11 parameters and 1 required, the description covers pricing, parameter interactions, return fields, errors, and edge cases (e.g., auto_job). Combined with the output schema, it leaves no critical 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?

Despite 0% schema description coverage, the description adds rich meaning for parameters like mode (cost implications), count (range), style (mode-dependent behavior), and verbosity, compensating fully for the schema's silence.

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 'Generate ranked, scored viral hooks for a topic,' using a specific verb and resource. It distinguishes itself from siblings like generate_hooks_batch (batch) and list_hooks (listing) through its focus on single-topic generation.

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 detailed cost formulas, mode differences, and parameter behaviors (e.g., deadine_ms with auto_job). However, it lacks explicit comparison to siblings such as generate_hooks_batch, which would clarify when to use this tool versus 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?

Despite no annotations, description comprehensively details billing (all-or-nothing, per-item pricing, mixed tiers), idempotency, verbosity, streaming, error types, and return shape. No contradictions.

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?

Single paragraph packs many details efficiently. Front-loaded with main purpose. Slightly dense but not overly verbose. Could benefit from listing.

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 tool complexity (7 params, nested array, pricing, errors, streaming), description covers purpose, billing, safety, streaming, errors, and return shape. Output schema exists, reducing need for return value explanation.

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 0%, so description must compensate. It covers mode, idempotency_key, tags, verbosity, but omits api_key, platform, requests structure. Partial coverage.

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

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

Description clearly states 'Generate hooks for many topics in ONE call', specifying the verb and resource. It distinguishes from sibling tools like generate_hooks by emphasizing batch operation.

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 guidance on when to use (for multiple topics) and mentions idempotency for safety. Implicitly contrasts with single-topic sibling. Could explicitly state when not to use.

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

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

Annotations already provide readOnlyHint=true. The description adds 'no API key echoed back' (privacy), 'Free read' (no cost), lists exact return fields, and mentions errors (unauthorized, rate_limited). This enriches the agent's understanding beyond 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 lines with a clear summary sentence followed by structured return fields and errors. Every sentence adds value with no redundancy.

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

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

Covers return fields and errors, and output schema exists. However, the tool has one parameter that is not explained, leaving a significant gap for such a simple tool.

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

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

With 0% schema description coverage, the description must explain the api_key parameter, but it completely omits its purpose or usage. The agent is left to guess how to supply the API key.

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?

Clearly states it returns account state and specifies it doesn't echo the API key. The phrase 'Free read' reinforces that it's a read operation. Among siblings like get_usage and get_webhook, this uniquely identifies account info retrieval.

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?

Implies usage for retrieving account state but lacks explicit guidance on when to use vs alternatives like get_usage or list_keys. No mention of when not to use 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?

The description discloses behavior beyond the readOnlyHint annotation by explaining that in_flight merges live-ops with queued/running jobs and recent shows completed charged ops. It mentions errors and an SSE feed. 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 adequately sized but includes some redundant phrasing (e.g., 'Free.') and could be more concise. Key information is front-loaded, but overall structure is acceptable.

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

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

Given the tool's simplicity (2 parameters, no required), the description provides sufficient context: it explains the two types of activity returned and mentions the SSE feed. It does not detail the output schema, but that is handled by the output schema itself.

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 0% schema description coverage, the description adds crucial meaning: it specifies recent_limit range (1-100, default 20) and the api_key parameter. This compensates for the schema's lack of descriptions.

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 shows account agents' activity, distinguishing between in-flight and recent operations. It specifies the resource and scope, but does not explicitly differentiate from sibling tools like list_jobs or get_job, which could cause confusion.

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 mentions the tool is free and lists possible errors (unauthorized, rate_limited), but provides no guidance on when to use this tool versus alternatives. It lacks explicit usage context such as prerequisites or scenarios.

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. The description adds value by detailing the return format (including p50/p90 latency, source, advice) and stating it is free and requires no authentication, which goes beyond structured metadata.

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

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

The description is concise with a clear front-loaded purpose. It uses a few sentences efficiently, though the return format detail could be shortened slightly.

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 an output schema (implied but not shown), the description adequately covers return structure and usage context. It could elaborate on 'advice' but remains complete for typical use.

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?

No parameters exist; schema coverage is 100%. Baseline score of 4 applies, and the description does not need to add param info.

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 'measured/expected wait per generation mode' with a specific verb ('get') and resource ('estimates'). It distinguishes from siblings by mentioning 'size a call before spending', which implies cost estimation before using generation 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?

Explicitly states 'Free, no auth' and advises to 'Size a call before spending', indicating when to use. However, it does not mention when not to use or compare directly with alternatives like 'pricing'.

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 annotation, the description adds scope ('Account-scoped: a foreign or unknown id is not_found (no existence leak)') and detailed return structure. 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?

Description is dense and includes some extraneous details ('Free (WP-G)'). Could be more streamlined, but the key information is front-loaded and clear.

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?

Covers purpose, input sources, scope, errors, and return structure. With an output schema present, the description is still self-contained and provides all necessary context for a fetch 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?

With 0% schema description coverage, the description compensates by stating that hook_id comes from specific responses. api_key is mentioned but not elaborated. Adds meaningful guidance beyond the raw 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?

Description clearly states 'Fetch one bought hook in full, including its parsed score.' It uses a specific verb (fetch) and resource (bought hook), and distinguishes from sibling tools like list_hooks, generate_hooks, etc.

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 context on where to get hook_id ('from a generate/batch/remix response or list_hooks') and mentions error types. Lacks explicit when-not-to-use instructions, but the purpose is clear enough.

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

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

Adds significant behavioral details beyond readOnlyHint annotation: polling logic, status transitions, error handling, and security behavior (no existence leak on foreign id). 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?

Compact and well-structured, front-loaded with purpose. Some repetitive language but overall efficient.

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

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

Covers purpose, usage, behavior, and return format. Missing explicit parameter descriptions, but output schema is mentioned. Good for a single-job polling tool.

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

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

Schema description coverage is 0% and description only implicitly mentions job_id via context. The api_key parameter is not described. The output fields are detailed but parameter semantics are sparse.

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 clearly that it polls an async job for status, progress, and result. Distinguishes from sibling tools like list_jobs and start_generate_job by focusing on a single job's status.

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?

Explains when to poll (after poll_after_seconds), expected statuses, and access restriction (only owning account). Does not explicitly mention alternatives but enough context given 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?

The description adds context beyond the readOnlyHint annotation by stating it is 'Free, no auth.' and that it returns structured data. However, it does not disclose any potential rate limits, response size, or other behaviors. With annotations already covering safety, the description adds moderate value.

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: two sentences covering purpose, content, and access. Every word contributes meaning. No redundancy.

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

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

Given the tool's simplicity (no parameters, output schema exists), the description is fairly complete. It describes the return structure clearly. However, it could mention next steps or how an agent should use the returned data.

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 description coverage is 100%. The description correctly does not waste space on parameters. Baseline 4 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 tool provides a '5-step agent quickstart' and lists the returned fields. The verb 'quickstart' is slightly vague, but the description expands on it. It does not explicitly differentiate from siblings, but the tool's purpose is unique among the listed 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 the tool is for initial setup, but provides no explicit guidance on when to use it versus alternatives, nor any conditions or prerequisites. The phrase 'Written to be parsed and acted on' suggests it's a first step, but lacks clarity.

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=true. The description adds behavioral details: it returns credits, totals, recent ledger, and mentions errors (unauthorized, rate_limited). It also explains scoping filters (tag, key_prefix, request_id). No contradictions.

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

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

The description is concise and well-structured: front-loaded purpose, then parameter details, return format, and errors. Every sentence adds value with no redundancy.

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

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

Given 5 parameters (none required) and presence of output schema, the description fully covers return values, parameter behavior, and error conditions. It is complete for the tool's complexity.

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 0%, so description fully compensates. It explains each parameter: recent_limit (range 1-200, default 50), request_id (scope to call charges), tag + key_prefix (fleet filters), api_key. Provides clear semantics beyond schema titles.

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 explicitly states 'Return the credit balance, per-operation totals, and recent ledger,' clearly specifying the verb (return) and resource (usage data). It distinguishes itself from sibling tools like add_credits and get_account.

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 mentions 'Free.' and lists parameters but does not explicitly state when to use this tool versus alternatives or provide exclusions. Usage context is implied but not directly guided.

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. The description adds key behavioral context: the secret is never returned, the operation is free, and lists possible errors. This goes beyond the annotation's simple read-only indication.

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

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

The description is concise (~60 words) and well-structured: main purpose on first line, then separate bullet-like lines for args, cost, returns, errors. No redundant information.

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

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

Given the tool has an output schema, the description lists all return fields (url, created_at, last_delivery_status, last_delivery_at, events) and errors. Parameter is explained. Complete for a simple read 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 single parameter (api_key) has 0% schema coverage, so the description must compensate. It notes the parameter requires read scope, adding meaning, but lacks format or examples. Adequate but minimal.

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 the account's webhook URL and last delivery status, explicitly excluding the secret. It distinguishes itself from sibling tools like set_webhook and delete_webhook by emphasizing it is a free read.

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 indicates it is a free read and lists errors, but does not explicitly specify when to use it versus alternatives like list_webhook_deliveries or set_webhook. Usage is implied but not 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?

Beyond the readOnlyHint annotation, the description adds that it performs a 'real DB ping', caches outcomes for 60 seconds, and never makes an LLM call, which is valuable behavioral context.

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 very concise, front-loaded with the main purpose, and uses structured listing for return fields, with no wasted words.

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 simplicity of the tool, the presence of an output schema, and no parameters, the description provides complete context including caching behavior and what the tool does not do.

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, and the schema coverage is 100%. The description focuses on return fields and behavior, which is appropriate given the absence of parameters.

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 performs a 'real DB ping' and checks LLM key configuration, distinguishing it from sibling tools that handle different operations like credits, keys, and jobs.

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 notes it is 'Free' and explicitly states it never makes a live LLM call, providing clear context for safe and fast usage, though it does not mention 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.

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

Annotations already provide readOnlyHint=true. Description adds context of being free and no auth, and gives a preview of the return structure, which is consistent 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?

Two clear sentences plus a structured return example. Every sentence adds value, and the structure is easy to parse.

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 an output schema, the description covers purpose, return format, and how to use results with other tools. No 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?

No parameters exist, so baseline score of 4 applies. Description does not need to explain parameters.

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

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

Description clearly states the tool lists hook archetypes with psychology, platforms, and templates. It distinguishes from siblings by showing how IDs are used in other tools like generate_hooks and remix_hook.

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?

Mentions 'Free, no auth' and explains how to use returned IDs with other tools. Does not explicitly state when not to use, but given it's a simple listing tool, 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 indicate readOnlyHint=true, which is consistent with listing. The description adds behavioral details: hooks are persisted for 90 days, and errors include unauthorized and rate_limited. This provides useful context beyond 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 well-structured: starts with the core action, then adds retention info, parameter list, return format, and errors. It is relatively concise, though 'Free (WP-G)' is extraneous and could be removed without loss.

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 presence of an output schema (so return values are documented elsewhere) and annotations, the description covers purpose, parameters, retention, and errors. It is mostly complete for a list tool, though it could briefly mention pagination behavior beyond limit/offset.

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 descriptions are absent (0% coverage), but the description explains all 8 parameters with types, formats, and semantics (e.g., mode enum values, ISO timestamp for since, exact match for tag). This fully compensates for the lack of schema descriptions.

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

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

The description clearly states it lists hooks bought by the account, in newest-first order. The verb 'List' specifies the action, and the resource 'hooks this account has bought' is precise. This distinguishes it implicitly from sibling tools like get_hook (single hook) or list_outcomes.

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 explicit guidance on when to use this tool versus alternatives like get_hook or list_jobs. The description does not mention when to use filtering parameters or compare with other list tools, leaving the agent to infer from context.

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

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

Beyond annotations (readOnlyHint=true), description adds that results are summaries without result blob, lists return fields, and mentions possible errors (unauthorized, rate_limited). This covers safety and behavioral traits well.

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?

Description is a single paragraph with moderate conciseness, but the return format is embedded inline, reducing readability. Could be more structured with separate sections for parameters and returns.

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 an output schema exists (not shown), description already provides return structure and error conditions. Missing details like pagination behavior beyond offset/limit, but overall adequate for a list 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?

With 0% schema coverage, the description fully explains each parameter: limit (1-200, default 50), offset (>=0), and api_key. This adds essential 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?

Description clearly states it lists jobs, newest first, with summaries lacking result blob. It implicitly differs from get_job (single job) and start_generate_job (creation) but does not explicitly distinguish from siblings.

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 on when to use this tool versus alternatives like get_job or list_hooks. Parameter constraints (limit range, offset non-negative) are given but not usage context.

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

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

Annotations indicate readOnlyHint=true, and description adds valuable behavioral details: returns only prefixes, never raw keys, includes fields like daily_credit_cap, spent_today, and error types. 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 very concise: two sentences plus a bullet-like return format. Every sentence adds essential information, and it is front-loaded with the core purpose.

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 presence of an output schema (context says yes), the description thoroughly covers return fields, error conditions, and typical usage, making it complete for a list tool.

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

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

The optional 'api_key' parameter is not explained in the description, and schema coverage is 0%, so the description fails to add meaning beyond the schema; the parameter's purpose remains unclear.

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 'List this account's API keys' with specific details like 'PREFIXES only' and 'Admin scope', clearly distinguishing it from sibling tools like create_key or revoke_key that modify keys.

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

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

It states the tool lists API keys as prefixes and implies an admin scope, but does not explicitly state when not to use it or provide alternatives; however, the context of siblings makes it 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 declare readOnlyHint=true, and the description adds information about error types, pagination, and the composition of returned rows, which enriches transparency beyond annotations.

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

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

The description is front-loaded with a summary but contains redundant phrasing and unclear jargon ('per-hook it rides get_hook'). Could be more concise and 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?

The description explains all parameters, return structure, and errors. It covers pagination limits. Minor gap: no explanation of the 'per-hook' relationship, but overall sufficient for usage.

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?

Despite 0% schema coverage, the description fully documents every parameter with allowed values, constraints, defaults, and the return shape, compensating completely for the schema's lack of descriptions.

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

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

The description clearly states it lists outcomes reported by the account, ordered newest first. It identifies the resource and action but does not explicitly differentiate from siblings like list_hooks or report_outcome.

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 explains parameters and return format but does not provide explicit guidance on when to use this tool versus alternatives. It implies bulk retrieval but lacks when-to-use or when-not-to-use 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 annotational readOnlyHint, the description discloses retention (dead rows kept 7 days), response structure (payload preview limited to 200 chars, full body never returned), and error types (unauthorized, invalid_request, rate_limited).

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

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

The description is front-loaded with the core purpose, then provides valuable usage guidance and parameter details. It is somewhat lengthy but every sentence adds necessary information, making it efficient for the use case.

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?

Description covers input parameters, output format (row structure), error handling, and retention policy. Combined with the presence of an output schema, it provides a complete picture for an agent to use the tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by detailing each parameter: status with allowed values, limit range (1-200), offset >=0, and api_key. It adds meaning beyond the schema's titles and defaults.

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 lists webhook deliveries for the account, newest first. It distinguishes from siblings like list_hooks and list_jobs by using the specific term 'deliveries' and noting it's a 'free read'.

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: 'Verify your receiver end-to-end... and diagnose failures without waiting out a real event.' It implies usage for monitoring and testing but does not explicitly state when not to use or name 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, and the description adds that it requires no authentication and is free. It also details the output structure including signup_grant and low_balance_threshold, providing context beyond the annotation.

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?

Single paragraph with key information front-loaded. Could be more structured with bullet points, but it is concise and covers the necessary details without excess.

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?

Complete for a zero-parameter read-only tool with an output schema. The description explains all major fields and formulas, leaving no ambiguity about what the tool returns.

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?

No parameters exist; schema coverage is 100% trivially. Description does not need to add parameter info. Baseline of 4 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?

Clearly states it is a machine-readable price list with per-mode expected_wait, free and no auth. Differentiates from siblings like add_credits or get_account which involve mutations or account-specific data.

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?

Implied usage for retrieving pricing information, but no explicit guidance on when to use versus alternatives like get_usage or get_estimates. Mentions it is free and no auth, but no when-not conditions.

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 no annotations, the description fully discloses behavior: it resets to pending, due now, re-attempts through normal pipeline, and if it dies again, dead-letters normally. It also lists possible errors. This is comprehensive for a mutation tool.

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

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

The description is relatively concise, front-loading the purpose and then providing key behavioral notes. It could be slightly better structured (e.g., separate lines for args and errors), but it is efficient and free of verbosity.

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 is a mutation with parameters and an output schema exists, the description covers the input, behavior, error conditions, and return (refreshed row). It is largely complete, though a note about idempotency or retry behavior could enhance it.

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

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

The input schema has 0% description coverage, but the description adds meaning: it explains that `delivery_id` comes from list_webhook_deliveries and that `api_key` is an optional argument. This helps the agent understand parameter sources and requirements.

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: 'Requeue a dead-lettered webhook delivery: reset to pending, due now.' It uses specific verbs and resources, and the mention of 'Admin scope' differentiates from non-admin tools. Among sibling tools like delete_webhook or set_webhook, this one is unique.

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 specifies that the tool is 'Valid ONLY on a `dead` delivery' and explains other statuses result in errors. It also mentions errors like conflict and not_found. However, it does not explicitly compare to alternatives or state when not to use it in favor of another tool.

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

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

With no annotations provided, the description carries the full burden. It discloses determinism per input, billing behavior, and possible errors. It also specifies the return structure in detail. A 5 would require explicit mention of idempotency or rate limits.

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 paragraph that front-loads the purpose immediately. It uses compact notation for parameters and is free of redundancy. Could be slightly more structured, but it's efficient.

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

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

Given the tool has 7 parameters, an output schema, and a complex mutation use case, the description completely covers input constraints, output structure, error types, and billing. It provides everything an agent needs to correctly invoke the tool.

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

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

Schema coverage is 0%, so the description must compensate. It lists all 7 parameters with constraints (e.g., text 3-300, count 1-5, tags as fleet slugs) and explains target_archetype references list_archetypes. This adds significant value beyond the schema's minimal titles.

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 starts with 'Rewrite an existing hook into a target archetype', which is a specific verb+resource combination. It clearly distinguishes from sibling tools like generate_hooks (which generates new hooks) and score_hook (which scores existing hooks).

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 on credit cost, determinism, and billing policy ('Billed only for variants returned'). It also lists common error types. While it doesn't explicitly say when not to use it, the purpose is sufficiently clear to differentiate from 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?

With no annotations provided, the description fully discloses behavioral traits: 'honest telemetry' (no fabrication), caps and rate limits, conflict on exact duplicates, idempotency key usage, and detailed error types. This level of detail is exemplary.

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

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

The description is dense but every sentence carries value. It is front-loaded with the core purpose, lists parameters concisely, then covers caps, return structure, and errors in a logical order. No redundant words.

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

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

Given the tool's complexity (9 parameters, no schema descriptions or annotations), the description covers all essential aspects: parameters with constraints, rate limits, idempotency, return schema, and error types. It provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0%, yet the description adds crucial constraints for every parameter: 'platform' enum, 'posted_at' ISO format and freshness limit, 'views/likes' range, optional fields with conditions ('http(s)+host' for url). This fully compensates for the absence of schema descriptions.

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: 'Report what a bought hook actually did once posted.' It distinguishes itself from sibling tools like 'score_hook' (predictive) and 'list_outcomes' (listing) by emphasizing 'no view prediction claimed' and 'honest telemetry'.

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 implicitly indicates when to use the tool (after posting to report actual outcomes) and mentions constraints like caps (20/hook, 500/day) and duplicate conflict. However, it does not explicitly state when not to use or name alternatives, which would have improved clarity.

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?

Describes the effect ('it stops working, others keep working'), the return fields including `already_revoked` for idempotency, and the authentication requirement. The idempotentHint annotation is consistent, and the description adds context about behavior. No contradictions.

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

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

The description is concise yet covers all necessary information: purpose, usage, parameters, constraints, return values, errors. No extraneous text. Structured with line breaks for readability.

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 two-parameter tool with an output schema, the description provides complete context: what it does, when to use, parameter explanations, constraints (last key, admin scope), errors, and return fields. No gaps remain.

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 description explains both parameters: prefix is 'the 12-char key prefix, e.g. vhg_sk_ab12', and api_key is 'a DIFFERENT active key to authenticate this call'. Since schema description coverage is 0%, this fully compensates and adds clarity beyond the schema.

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

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

The description clearly states the action ('Revoke the key with `prefix`') and the resource (key identified by prefix). It also distinguishes from `list_keys` by referencing it as the source of the prefix, making the 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?

Explicitly says when to use ('Use to kill a leaked or old key') and when not to ('You cannot revoke your LAST active key - create a replacement first'). Provides alternative action (create replacement) and error conditions, including what authentication is needed (admin scope, api_key parameter).

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 no annotations provided, the description carries the full burden. It discloses key behaviors: deterministic (non-LLM), credit charging, idempotency for replay, and error types. This is valuable beyond the schema, though it could explicitly state that no data is mutated.

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

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

The description is dense but well-organized, with a front-loaded purpose and a second paragraph using bullet-like structure for details. Every sentence adds value, though the bullet format is slightly compressed.

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 6 parameters, 1 required, and existing output schema, the description covers core behavior, return value structure, error types, and cost. It is nearly complete, but the 5 scoring dimensions are not listed (though 'rewrite tips' is mentioned).

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 0%, so the description compensates by explaining parameter constraints (text 3-300, platform options, tags 1-5 fleet slugs, verbosity levels, idempotency for replay). This adds significant meaning beyond the raw schema, though api_key and idempotency_key usage could be more detailed.

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 starts with 'Score any hook text on 5 dimensions with rewrite tips,' which clearly states the verb (score), resource (hook text), and scope. It also mentions 'Deterministic heuristic scorer (no LLM),' distinguishing it from generative tools like generate_hooks.

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 mentions '1 credit' as a cost but does not explicitly state when to use this tool versus siblings like score_hooks_batch. There is no guidance on when not to use it or alternatives, leaving the agent to infer usage from context.

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

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

No annotations are provided, so the description carries the full burden. It discloses credit cost, all-or-nothing charging, character and count limits, and mentions specific behavioral notes like 'never view prediction'. It does not explicitly state non-destructiveness but implies it through scoring context.

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

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

The description is dense and front-loaded with the main purpose. It covers usage, constraints, return formats, and errors in a single paragraph. While effective, it could be broken into clearer sections for improved readability.

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

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

Given the tool's complexity (two modes, multiple parameters) and the existence of an output schema, the description covers essential aspects: mode selection, parameter interactions, return shape hints, and error types. It does not detail the output schema further but that is acceptable. Minor gaps exist in explaining optional parameters.

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 0% schema description coverage, the description adds crucial meaning by explaining the relationship between 'texts' and 'sets' and the compare flag. It also outlines constraints like 2-4 sets and total 25 texts. However, it only lists other parameters (platform, tags, etc.) without explaining their purpose or defaults.

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 scores hooks in batch, with two modes: plain scoring or comparing named sets. It distinguishes from siblings like score_hook (singular) and generate_hooks_batch by emphasizing batch and comparison features.

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 specifies when to use each mode (plain vs compare) with explicit constraints on parameter presence and ranges. It also lists error types. However, it does not explicitly contrast with similar sibling tools like score_hook.

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?

No annotations; description fully carries burden. Discloses: secret returned once, destructive on re-registration (rotates secret), admin scope, free cost, errors (unauthorized, forbidden, etc.), verification method, and pinging mechanism.

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?

Well-structured with bullet points, front-loaded key info. Slightly verbose but each sentence adds value. Could be tighter.

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 output schema exists (though not provided), description covers return fields {url, secret, created_at, events, note, test_delivery_id}, errors, and side effects. Complete for a registration/replacement tool.

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

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

Schema coverage 0% so description must compensate. Adds meaning: url must be https, no creds, public host, length 1-2048. api_key is admin. Does not detail every parameter aspect but significantly adds value.

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?

Clearly states verb 'register (or replace)' and resource 'webhook', distinguishing from siblings like delete_webhook, get_webhook. Includes scope 'Admin'.

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?

Describes when to use: webhook for job.succeeded/job.failed/credits.low events. Notes that re-registering rotates secret (not a no-op). Lacks explicit when-not scenario, but 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?

The description adds significant behavioral context beyond the idempotentHint annotation: API key shown once, new accounts get 500 credits, idempotency key ensures no double grant, lists errors. 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 structured into paragraphs and bullet points, making it readable. However, it is somewhat verbose; a slightly shorter version could retain all key information.

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

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

Given the complexity of a signup tool, the description covers input, behavior, errors, and return fields. With an output schema present, it is complete and well-rounded.

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 0%, but the description explains all three parameters: name (1-100 chars, default agent), email (optional, contact hint never required), and idempotency_key (replay returns same account, never re-grants). This adds meaningful semantics beyond the schema.

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

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

The description clearly states 'Create an account and return your API key exactly once.' It identifies the specific verb and resource, and distinguishes from sibling tools like create_key (which probably requires auth) and delete_account.

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 explicitly says 'No auth needed' and 'the entry point for an agent with nothing', indicating when to use. However, it does not explicitly contrast with other tools or mention 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.

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

Describes that charge runs on the worker, results are always full-verbosity, and lists return fields (job_id, status, estimated_seconds, etc.) and errors (including idempotency_conflict consistent with idempotentHint). 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?

Front-loaded with main action and polling instruction. Includes return structure and errors in a compact paragraph. Could be slightly trimmed but generally efficient.

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

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

Given 10 parameters and 0% schema coverage, description covers async behavior, polling, return fields, key parameter constraint, and errors. Lacks details on mode, count, style, etc., but overall sufficient for basic use. Output schema exists but not described.

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 0% per context, but description adds meaning for topic/topics relationship (mutually exclusive). Other parameters (mode, count, style) are not explained; description references 'Same args as generate_hooks' without elaboration.

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 'Submit a generate as an async job; poll get_job for the result', specifying the verb (submit) and resource (generate job). It distinguishes from generate_hooks by noting it is async and polling-based, and explains the topic vs topics exclusivity.

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

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

Explicitly says 'prefer for research' and details the topic/topics constraint ('EITHER topic OR topics... both or neither = invalid_request'). It compares to generate_hooks (same args) but does not explicitly exclude other siblings like generate_hooks_batch.

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