VHGENGINE

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

Beyond the idempotentHint annotation, it details that replay with the same key does NOT grant twice, lists specific error categories (unauthorized, invalid_request, idempotency_conflict, rate_limited), and states the return shape. This is rich behavioral disclosure that annotations alone do not provide.

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 (plus an error list) with no wasted words. It front-loads the purpose and packs behavioral details, auth modes, and errors into a compact block.

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 existence of an output schema, the description still covers auth modes, idempotency, errors, and a high-level return value. It is thorough for a 4-parameter tool with complex deployment-dependent behavior.

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

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

Schema coverage is 100% with descriptions for all parameters, which is a baseline 3. The description adds meaningful context for admin_key (required only when configured) and idempotency_key (replay semantics), going beyond the schema. This pushes it to a 4.

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 'Top up your credit balance (1-10000)' — a specific verb, resource, and range. This clearly distinguishes it from billing/checkout siblings and conveys the core action immediately.

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 explains when admin_key is required versus self-serve, and idempotency behavior. However, it does not explicitly contrast with alternatives like create_checkout or state when not to use this tool. Context is clear but no exclusions are given, matching a 4.

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

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

Goes far beyond the destructiveHint=true annotation. Discloses non-refundable behavior ('never refunds'), the absence of refunds for queued jobs ('credits_refunded is always 0'), post-cancellation status ('reads as status \"failed\"'), and the idempotency quirk ('reusing the cancelled one replays the cancelled result'). Also enumerates error conditions: unauthorized, forbidden, not_found, 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 compact yet information-dense. Front-loaded with the primary action, each sentence adds critical operational detail (status handling, refunds, errors, idempotency). 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?

Despite having full schema coverage and an output schema, the description adds necessary behavioral context: what counts as cancellation, why refunds are always 0, how cancelled results appear, and how to handle errors. This is more than sufficient for an agent to safely 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 description coverage is 100%, so baseline is 3. The tool description does not add parameter-specific semantics beyond what the schema already provides (e.g., job_id's account-scoping and api_key's fallback chain). The description's idempotency_key note is about a different call, not this tool's 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 opens with 'Cancel a job that is STILL QUEUED,' which states the exact verb, resource, and condition. It clearly distinguishes from sibling tools like get_job, list_jobs, start_generate_job, and wait_for_job by narrowing the scope to queued jobs only.

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

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

Explicitly states when to use: 'Cancel a job that is STILL QUEUED.' Provides a when-not: 'A RUNNING job cannot be stopped: it finishes, CHARGES and persists.' Offers an alternative for re-running: 'resubmit with a FRESH idempotency_key.' It also directs the caller to branch on 'cancelled' and use 'reason + next_action.'

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 available, the description carries the full burden and does well: it discloses that no card is touched, that the webhook credits after payment, and lists the return fields and error types. It gives a solid understanding of the async credit flow and failure modes, though it omits details like idempotency or rate-limit specifics.

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 and concise: a one-line purpose, a short behavior note, then clearly labeled Args, Returns, and Errors sections. Every sentence adds value, and the format is scannable for an agent. 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?

Given the tool's moderate complexity (payment flow, async crediting, multiple error modes), the description covers the essential behavioral context. It explains the user-facing flow, return object, and error conditions. Since an output schema exists, the return values are already structured, and the description complements that without redundancy.

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

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

The input schema already covers all parameters with detailed descriptions (100% coverage). The description adds minimal extra semantic value, mainly restating 'pack' as a credits amount and adding 'spend scope' for api_key. Since the schema does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get a Stripe hosted-checkout link for a credit pack.' This clearly states what the tool does and distinguishes it from related tools like add_credits. It also explains the token flow ('You never touch a card') and the intended use case, 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?

The description provides clear context for when to use the tool: to generate a checkout link that is handed to a human for payment. It mentions an explicit alternative in the error section: 'payments_disabled (503; use add_credits)'. However, it does not provide broader when-not-to-use guidance beyond that specific error case, so it stops short of a full 5.

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

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

The description discloses multiple behavioral traits beyond the idempotentHint annotation: it returns 'the exact version, deny-by-default secondary-use decisions, receipts, and an unverified-attestation warning' and lists specific error codes. It also explains idempotency_key replays safely, adding meaning to 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?

The description is compact and front-loaded with the key purpose. All sentences add value: cost/scope, validation requirement, return values, idempotency, and error list. The error list is concise and the overall structure is efficient 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 tool's complexity (10 parameters, output schema, annotations), the description covers essentials: cost, permissions, minimum content, return payload, idempotency behavior, and errors. It complements the rich schema without repeating it, providing sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds a crucial cross-parameter constraint: 'At least one creator/audience/stance/fact is required,' which is not evident from individual optional fields. It also highlights idempotency_key replay safety, supplementing the schema's description.

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 owned, versioned creator profile' with a specific verb and resource. It distinguishes the create operation from sibling tools like update_creator_profile, delete_creator_profile, and list_creator_profiles by focusing on creation and the 'owned, versioned' aspect.

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

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

The description provides clear context: 'Free; admin scope' indicates cost and permission prerequisites, and 'At least one creator/audience/stance/fact is required' gives a content constraint. It also notes optional idempotency_key replay safety. It doesn't explicitly name alternatives, but the create-vs-update distinction is clear 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?

With no annotations, the description carries full burden. It discloses the one-time plaintext return, admin scope requirement, full-power vs scoped behavior, daily cap semantics, auth parameter, return fields, and error types. This is rich, honest behavioral disclosure.

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

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

The description is structured into a quick-essential first line, a delegation rationale paragraph, then compact Args/Returns/Errors lines. Every sentence adds value—no fluff or repetition—and it stays focused despite covering critical security details.

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 tool has 4 params, an output schema, and genuine complexity (auth scopes, caps, one-time secret). The description covers purpose, usage, return shape, auth requirements, and error cases. It is complete enough to invoke correctly without external 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?

Schema coverage is 100% and the schema descriptions are already strong, but the description adds clarifying meaning: 'omit for full power,' 'store it' for the returned api_key, and 'admin-scoped key' for the api_key parameter. This goes beyond the schema baseline.

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

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

The description opens with 'Mint a new named API key; the plaintext is returned ONCE. Requires admin scope,' which uses a specific verb ('mint'), resource ('API key'), and key trait (one-time plaintext). This clearly distinguishes it from siblings like list_keys, revoke_key, and add_credits.

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

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

It explicitly states the admin-scope requirement and positions delegation use cases: 'Delegate safely... hand a sub-agent a key that can only do what you allow.' It does not name alternative tools, but the purpose is clearly distinct from revoke_key or list_keys, and the context is sufficient.

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

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

Beyond the destructiveHint annotation, the description details exactly what is revoked/deleted (keys, profile facts, hooks, webhooks, deliveries, jobs, idempotency) and what is retained (retraction markers, ledger, outcome rows). It also emphasizes irreversibility ('TERMINAL, not reversible') and the confirm guard.

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 provides essential information: terminal action, scope, guard, effects, retention, export first, pagination, and errors. It is front-loaded with the most critical words ('Permanently delete this account') and is well-structured despite its length.

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 and high stakes, the description covers all necessary context: what is destroyed, what is kept, how to prepare (export), how to list data, and error handling. It is fully complete for a destructive account-deletion tool, and the presence of an output schema further covers return values.

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

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

The input schema already provides complete, precise descriptions for both `api_key` and `confirm` (including the `const: "delete"` guard). The description only repeats the confirm requirement ('Pass confirm="delete"'), adding no new parameter-specific meaning beyond the schema, so it does not exceed the baseline.

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

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

The description opens with 'Permanently delete this account,' which uses a specific verb and resource, and is clearly distinct from sibling tools like delete_creator_profile and revoke_key. It also clarifies the scope ('Admin scope (WP-LIFE)') and the terminal nature of the 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?

It explicitly states when to use it (admin scope) and includes a critical prerequisite: 'Export FIRST with export_usage.' It also provides alternative listing tools for paged access (get_usage/list_hooks/list_outcomes/list_jobs) and expected errors, guiding the agent on correct invocation and safety.

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?

Even with annotations declaring destructive and idempotent hints, the description adds substantial value: what is retained (retraction marker), that committed hook outputs are not touched, that no data is used for secondary learning, and the one-way replay-key tombstone mechanism. It also lists the full error set, providing excellent behavioral transparency.

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 core statement is front-loaded with an efficient first sentence. Additional sentences provide necessary caveats and error handling, though the privacy sentence about secondary learning is somewhat tangential. Overall structured and scannable.

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

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

The description covers what is erased, what is retained, authorization scope, side effects, idempotency behavior, required parameters, and error scenarios. Given the output schema exists, it need not explain return values; it is fully 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 100%, but the description adds meaning beyond the schema: it ties expected_version and confirm to safety requirements, and explains the idempotency_key behavior via tombstones. This is more than baseline but does not deeply elaborate every parameter.

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 ('Erase') and resource ('profile facts and consent history') with a clear nuance ('retain a retraction marker'). It also specifies admin scope, which distinguishes it from sibling tools like update_creator_profile or 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 clearly indicates administrative scope and prerequisites ('Admin scope', 'Requires the current expected_version and confirm="delete"'). However, it does not explicitly name alternatives or state when not to use it, though the context strongly implies its use for full erasure rather than updates.

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

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

The description adds substantial behavioral context beyond the idempotentHint annotation: it states admin scope is required, cost is free, returns {deleted: true}, and enumerates possible errors including not_found when no webhook is registered. This clarifies edge cases like repeated deletions and rate-limiting. 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 extremely compact and well-structured, segmented into Args, Cost, Returns, and Errors. Every sentence earns its place and there is no redundant 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 simple one-parameter delete tool, the description covers prerequisites, cost, return value, and all relevant error conditions. It even clarifies idempotency behavior by noting that deleting a non-existent webhook yields not_found, which is important for repeated calls. The output schema exists, and the description is complete enough for an agent to invoke correctly.

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

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

The schema already provides detailed fallback semantics for api_key with 100% coverage, so the baseline is 3. The description adds the requirement that the key must have admin scope, which is additional meaning not present in the schema, elevating it to 4.

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 the specific verb 'Remove' and identifies the resource as 'this account's webhook,' clearly distinguishing it from sibling tools like set_webhook, get_webhook, or delete_account. The '(WP-M)' is slightly cryptic but does not obscure the 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 implies the tool is for deleting the account webhook and notes the admin scope prerequisite, but it does not explicitly discuss when to use it relative to alternatives or provide any exclusions. It would benefit from mentioning that set_webhook is for creation/updating.

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

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

Discloses many non-obvious behaviors—unbounded output, email masking without admin scope, filters only narrow ledger events while other categories remain complete, and error conditions. Annotations only mark readOnlyHint, so this description carries the burden and exceeds it.

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

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

The description is long but information-dense; every sentence delivers a distinct caveat or clarification. It opens with the primary action and front-loads key facts (free, before delete_account) before detailed return categories. Slight redundancy between the first sentence's data list and later 'Returns...' list, but not enough to be wasteful.

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 high-complexity export tool with optional filters and a rich result set, the description covers behavior, scoping, auth, errors, and return composition. Since an output schema is present, return-value details are bonus; the operational caveats are the critical missing context and are included.

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 already describes tag/key_prefix fully (100% coverage). Description adds critical cross-parameter semantics: 'Filters narrow ledger events only; all retained data categories stay complete,' which clarifies that key_prefix/tag do not limit hooks, jobs, profiles, etc. It also notes error cases tied to auth.

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

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

Description opens with specific verb 'Export' and enumerates exact data categories (ledger, hooks, instances, lineage, outcomes, profiles, retained jobs). It distinguishes this from lighter paged reads by warning 'UNBOUNDED: prefer paged reads on big accounts' and by tying it to the pre-delete_account snapshot use case.

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 clear usage conditions: free, run before delete_account, not suitable for large accounts ('prefer paged reads'). It does not name specific sibling alternatives but gives enough contextual guidance to choose export vs paged reads.

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 of behavioral disclosure, and it does so richly. It discloses cost structure, deterministic behavior, cancellation effects, idempotency requirements, async fallback, and error types, giving the agent a clear picture of side effects and constraints.

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 core purpose, and each sentence adds substantive information. However, the block-with-newlines formatting is somewhat unstructured compared to clean bullets or separate sentences, though no content is wasted.

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 28 parameters and existing output schema, the description covers the most critical behavioral and operational context: pricing, cancellation, idempotency, async job handling, and error conditions. It does not explicitly address the relationship to batch generation, but the output schema and parameter descriptions cover many details, so it is reasonably 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?

The input schema already has 100% parameter description coverage, so the baseline is 3. The tool description adds a high-level cost formula referencing mode and count, but it does not add per-parameter semantics beyond what the schema already provides.

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

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

The opening phrase 'Generate ranked, scored hooks for a topic' is a specific verb+resource statement that clearly identifies the tool's core function. However, it does not explicitly distinguish this tool from close siblings like generate_hooks_batch or remix_hook, so it misses the top score.

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 operational guidance (e.g., auto_job polling, idempotency key usage, error handling) but does not state when to use this tool versus alternatives. There is no mention of generate_hooks_batch for batch scenarios or remix_hook for variations, so the agent is not told which sibling to prefer.

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 carries full burden and excels by disclosing non-obvious behaviors: 'CANCELLING DOES NOT REFUND', idempotency_key requirement, auto_job polling, and profile pair return behavior. However, it references 'auto_job' which is absent from the provided input schema, creating potential confusion.

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 efficient, front-loading the core purpose and then adding operational warnings, billing details, async behavior, and errors in a logical sequence. Every sentence earns its place 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?

For a 24-parameter batch tool with an output schema, the description covers critical operational aspects: atomicity, pricing, cancellation danger, idempotency, async polling, profile results, and error names. The only notable completeness gap is the auto_job parameter not appearing in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable cross-parameter context: per-item pricing formula ('base + per_hook * returned'), batch-level scope of mode/key/tags, and idempotency guidance. The phantom auto_job reference slightly reduces reliability.

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

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

The opening sentence 'Generate many topics in one atomic, all-or-nothing charged call' gives a specific verb+resource+scope, clearly distinguishing this batch tool from the single-topic generate_hooks sibling. The name and description align perfectly.

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 conveys when to use this tool: when you need many topics generated in a single atomic, all-or-nothing call. It also warns about cancellation/refund policy and idempotency, but it does not explicitly name alternatives like generate_hooks or explicitly say 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?

The description goes beyond the readOnlyHint annotation by explaining that it is a 'free read' (likely not billing-consuming), that it counts against rate limit, that no API key is echoed back, and lists likely errors. This is rich behavioral context 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 front-loaded with the main purpose and then provides useful details in a structured way. It is slightly verbose with the rate_limit field listing, but every sentence adds value and it remains readable.

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 account info tool, the description covers purpose, usage guidance, rate-limit semantics, error cases, and response details (rate_limit fields). An output schema exists, so return values need not be described exhaustively, but the description provides ample context.

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 schema already fully documents the `api_key` parameter including fallback behavior. The description adds no new parameter information, so 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 tool returns the account's state and remaining rate-limit budget, which is a specific verb+resource combination. It distinguishes itself from sibling tools like get_usage or list_keys by focusing on account-level rate-limit information.

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

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

The description gives concrete usage guidance: use it to check `remaining` before pacing a fleet, and warns that the read itself consumes a rate-limit call. It does not explicitly name alternatives, but the context for when to use it 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?

The description adds rich behavioral context beyond the readOnlyHint: it explains that in_flight merges a live-ops registry with queued/running jobs, recent contains last completed charged ops, each row has a human-readable message, and it even mentions the SSE feed. It also discloses error conditions like unauthorized and 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 well-structured and front-loaded with the main purpose, then expands into details. The 'Free.' sentence and markdown formatting add some noise, but all sentences carry useful operational information (args, errors, SSE feed).

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

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

For a read-only activity tool with an output schema and an annotation, the description is thorough: it covers the distinction between in_flight and recent, mentions the SSE alternative, lists errors, and parameter behavior. There is no significant missing context that would prevent an agent from using the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already fully documents api_key and recent_limit. The description only repeats the arg names and limits, adding no new meaning beyond the schema 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?

The description clearly states the tool shows 'what this account's agents are doing' with 'in-flight ops + recent ops', providing a specific verb and resource. It distinguishes itself by covering agent activity rather than generic jobs/runs, though it does not explicitly name 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?

Usage is implied through the description of the activity overview ('See what this account's agents are doing'), but there is no explicit guidance on when to use this instead of alternatives like list_jobs or list_runs, and no exclusions are provided.

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

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

Annotations only declare readOnlyHint=true, but the description adds valuable behavioral context: uniform not_found envelope for foreign/deleted/unknown IDs, return consistency with REST, and a specific error list. This exceeds annotation coverage and provides useful operational expectations.

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

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

The description is concise and front-loaded with the core purpose. The additional sentences about error envelopes and REST parity are useful, though the error list could be considered slightly verbose for a description. Overall, it 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 tool with full schema descriptions, an output schema, and a read-only annotation, the description is comprehensive: it covers purpose, version selection, edge-case behavior, error types, and return consistency. The context is complete enough 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?

Since the input schema has 100% parameter description coverage, the description adds little beyond the schema. It echoes the version behavior ('current or one exact historical') but does not meaningfully enhance parameter understanding. 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 clearly states the tool's function: 'Get the current or one exact historical creator-profile version.' It uses a specific verb (Get) and resource (creator-profile version), and the scope ('current or one exact historical') differentiates it from sibling list/create/delete/update profile 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 by focusing on a single profile version with an optional version parameter, which distinguishes it from listing all profiles. However, it does not explicitly mention alternatives like 'use list_creator_profiles to list all profiles', so it falls short of full 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 the description adds meaningful context: it's free, requires no auth, and explains the source field's behavior (measured vs default) and advice. This goes beyond the structured annotation without contradicting it.

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

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

The description is a single dense sentence with the return structure embedded. It front-loads the core purpose ('measured/expected wait per generation mode') and immediately notes free/no-auth. While the nested return format is heavy, every phrase earns its place with no fluff.

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

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

For a parameterless, read-only endpoint with an output schema, the description delivers everything needed: purpose, usage timing, cost/auth status, and a detailed return-shape. There are no gaps for the intended use case.

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

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

The tool has zero parameters, so the schema provides no semantics. The description compensates by fully describing the return object: op, modes, per-mode p50/p90 timings, sample counts, source, and advice. This gives complete meaning to the tool's output.

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 function: returning measured/expected wait times per generation mode. The phrase 'Size a call before spending' gives a specific, actionable purpose that distinguishes it from cost-related siblings like quote or pricing.

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

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

The description provides clear context for when to use the tool ('before spending') but does not explicitly mention alternatives or exclusions. It implies a pre-call sizing use case, which is sufficient guidance without being exhaustive.

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?

Even though readOnlyHint annotation already signals a safe read, the description adds meaningful behavior: account-scoping with no existence leak, error types (unauthorized, not_found, rate_limited), cost (free), and a hint to report results via report_outcome. These details go well 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?

The description is well-organized with a clear purpose sentence followed by scoping, args, returns, and errors. It is slightly redundant with the schema's parameter descriptions, but each section carries useful information and the overall length is appropriate for the tool.

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

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

The description covers the full context: what the tool does, how to obtain the required ID, account scoping behavior, return structure, error conditions, and a follow-up action (report_outcome). Even with an output schema present, the explicit return field list and error handling make this highly 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?

The input schema already has 100% coverage for both parameters, with detailed descriptions for hook_id and api_key. The description merely restates the parameter sources without adding new meaning, so it meets the baseline but does not exceed it.

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

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

Description starts with 'Fetch one bought hook in full, including its parsed score,' which precisely states the action and resource. It distinguishes from sibling list_hooks (which lists) and score_hook (which scores) by focusing on retrieval of a single detailed 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?

The description tells you where hook_id comes from and that the call is free, but does not explicitly discuss when to use this versus alternatives like list_hooks or score_hook. Usage is inferred rather than 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?

With only readOnlyHint=true as annotation context, the description carries the full burden of behavioral disclosure. It thoroughly explains polling semantics, terminal states, result/error payloads, ownership scoping (no existence leak), and possible errors (unauthorized, not_found, rate_limited). This goes well beyond the minimal annotation and provides rich, non-obvious behavioral details.

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

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

The description is front-loaded with the core purpose and then efficiently expands into polling behavior, ownership, return fields, and errors. Every sentence adds essential information with no redundancy or fluff. The structured layout aids readability without excessive length.

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 poll-based async job tool, the description covers the full lifecycle: when to poll, how to interpret terminal statuses, the exact return shape, and error semantics. Even with an output schema likely existing, the description is self-sufficient for correct usage, including edge cases like not_found and rate_limited.

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 covers both parameters (job_id and api_key) with descriptions, so baseline is 3. The description adds no parameter-specific syntax beyond what the schema already provides; it merely references the return field poll_after_seconds, which is not a parameter. Thus, it neither enriches nor detracts from parameter understanding.

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

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

The description opens with a specific verb and resource: 'Poll an async job: status, real engine stage, progress, ETA, result/error.' This clearly identifies the tool's function and distinguishes it from siblings like list_jobs (listing) and cancel_job (cancelling), without needing to read beyond the first line.

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 a clear usage pattern: 'Poll after poll_after_seconds until status is succeeded or failed.' It also notes ownership constraints and not_found behavior. However, it does not explicitly mention alternatives such as wait_for_job or list_jobs for similar polling scenarios, so differentiation relies on context rather than explicit exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses the exact return structure ({what_this_is, five_steps, modes, wait_guidance, links}) and adds specifics like 'cost + live latency' and 'expected_wait, estimates, progressToken, jobs.' It also clarifies authentication requirements ('no auth') and that it is free, providing valuable context not captured in 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 two compact sentences with a clear bullet-like list of returned fields. It is front-loaded with the core purpose and avoids redundancy. Every sentence adds value, making it highly 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?

For a simple, zero-parameter tool with an output schema, the description provides complete context: what it is, what it returns, authentication, cost, and intended use. It even elaborates on output structure beyond the schema, making it fully self-contained for an agent.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly omits parameter details and focuses on output, which is sufficient. Schema coverage is trivially 100% with no params, and no additional parameter semantics are needed.

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

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

The description clearly states the tool is a '5-step agent quickstart' covering modes, wait guidance, and links. This distinguishes it from the operational sibling tools (e.g., get_job, create_key) which perform specific actions. The verb 'quickstart' and resource scope make 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?

The description implies this is the first tool to use by calling it a 'quickstart' and noting it is 'written to be parsed and acted on.' It also mentions 'Free, no auth,' indicating it can be called without prerequisites. However, it does not explicitly state when not to use it or compare it to alternatives, though no real alternatives exist among 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 annotation readOnlyHint=true already signals a safe read operation. The description adds value with error types (unauthorized, invalid_request, rate_limited), a 'Free' cost note, and a clear return shape including legacy metadata. It does not contradict annotations and provides additional behavioral context beyond the safety flag.

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

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

The description is compact and well-structured: first the one-sentence purpose, then a parameter summary, return shape, and errors. Each line earns its place and there is no repetition of schema fields. The formatting with line breaks aids scannability.

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

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

With an output schema present and readOnly annotation, the description is comprehensive: it covers scope, defaults, pagination hints, error conditions, and free usage. It even notes what each row carries. For a 6-param read-only tool, this leaves no critical gaps evident.

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 all six parameters precisely. The description's condensed parameter list (e.g., 'tag + key_prefix (WP-J fleet filters)') adds mild conceptual grouping but no new syntax or semantics. This meets the baseline expected when schema handles param detail.

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

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

The description opens with a specific verb ('Return') and three concrete resources (credit balance, per-operation totals, recent ledger), making the tool's function unambiguous. It distinguishes itself from siblings by scoping to 'recent ledger' rather than whole-history exports (export_usage), even without naming alternatives.

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 lacks an explicit statement of when to select this tool over related tools like export_usage or get_account. It implies usage by enumerating return values and mentioning 'Free,' but does not provide exclusions or alternatives. Thus it is adequate but not a strong usage guide.

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 critical behaviors: it never returns the secret, is free, requires read-scoped API key, and lists specific errors (unauthorized, not_found, rate_limited). This rich context helps the agent anticipate side effects and failure modes.

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 main purpose, followed by a structured Args/Errors list. It is compact but slightly dense in the second sentence; still every sentence earns its place, though it could be split 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?

With an output schema present and thorough annotations, the description covers all essential context: return fields, error modes, authentication requirements, and cost. No critical gaps are apparent for a single-parameter 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 input schema already covers the api_key parameter with 100% description coverage, including fallback mechanisms. The description adds only a minor 'read scope' note, which is already implied by the tool's read-only nature. Schema does the heavy lifting, so 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 tool retrieves the account's webhook URL and delivery status, explicitly excluding the secret. This distinguishes it from siblings like set_webhook, delete_webhook, and list_webhook_deliveries, which handle different aspects or collections.

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 use when you need the account webhook details, but does not explicitly contrast with alternatives like list_webhook_deliveries or get_hook. No when-not-to-use or alternative references are provided, so guidance is implied rather than explicit.

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

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

The description reveals several behavioral details beyond the readOnlyHint annotation: it never calls an LLM ('llm_configured never calls an LLM'), it reports on specific subsystems (queue, backups, integrity, source writer state), and it clarifies that schema readability is not equivalent to readiness. No contradiction with annotations; the readOnlyHint is consistent with a diagnostic probe. The disclosure is thorough, though it could explicitly state that the probe performs no writes.

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 ('Deep health:...'), then expands with necessary details. It is dense but every sentence adds value, covering return fields, semantic differences, and operational guidance. It could be slightly trimmed, but it remains well-structured and not wasteful.

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 and an output schema exists, the description goes beyond what's necessary by explaining what key return fields mean, how to interpret readiness vs schema, and what to check before starting a job. It provides complete context for an agent to correctly use this 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 input schema has zero parameters, and the description need not explain any. Baseline for no params is 4, and the description appropriately focuses on the tool's behavior and return values instead of adding unnecessary parameter 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 a specific verb+resource: 'Deep health: DB read+write probe, worker/queue, backup + integrity.' It distinguishes itself from sibling tools by being a health check rather than a job or account tool, and explicitly defines what 'ok' means. This makes the purpose immediately clear and distinct.

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

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

The description gives concrete usage context: it mentions using the same probes as GET /health (indicating a deeper diagnostic), and explicitly warns to 'check job_worker_alive before start_generate_job'. It also differentiates what readiness proves versus schema readability, helping the agent decide when this tool is needed. However, it does not explicitly state when not to use it or name alternative tools beyond that one suggestion.

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 useful context beyond the readOnlyHint annotation: it states the operation is free and requires no auth, and it discloses the exact return shape. Since annotations already cover the read-only nature, the description provides complementary behavioral details.

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

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

The description is two sentences, front-loaded with the main action, and includes a compact return format. Every sentence earns its place, providing both purpose and usage guidance without waste.

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, an output schema exists, and readOnlyHint is present, the description is fully sufficient. It covers what is returned, how to use the results, and cost/auth requirements, leaving 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?

The tool has zero parameters, so schema coverage is trivially 100%. With no parameters to explain, the baseline is 4. The description adds value by explaining how the returned ids are used in other tools, which helps the agent understand the output's role.

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 verb 'List' and the resource 'hook archetypes', specifying the included attributes (psychology, platforms, templates). It distinguishes itself from siblings like generate_hooks and remix_hook by showing how its output feeds into them.

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

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

The description implies when to use it: to get archetype IDs for generate_hooks or remix_hook. It also notes 'Free, no auth' as a usage condition. However, it does not explicitly contrast with alternative listing tools (e.g., list_hooks) or state exclusions.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavior: newest-first ordering, paging via limit/offset, response shape ({events, limit, offset, total}), and error types (unauthorized, invalid_request, rate_limited). This significantly exceeds the annotation and schema information.

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

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

The description is three concise sentences, front-loaded with purpose and cost, then paging, response format, and errors. No redundancy or unnecessary detail. Every sentence earns its place.

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

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

Given the presence of an output schema and detailed parameter schemas, the description still provides response shape and error conditions, making it complete for invocation. It doesn't cover every possible behavior, but for a simple list endpoint it is sufficient.

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

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

Schema description coverage is 100%, so the schema already explains limit, offset, and api_key thoroughly. The description only adds that limit/offset are used for paging, which is marginal. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the resource (billing events) and the action ('Recent billing events'), enumerates specific event types (usage.recorded, credits.granted, credits.low), and differentiates from siblings by focusing on billing events only. The verb and resource are specific and 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 clear context: it's a paged list with limit/offset like list_hooks and list_outcomes, and notes it's free. However, it doesn't explicitly state when not to use it or direct users to alternative tools for other event types, so it lacks explicit exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses the free cost, the exact return shape ({profiles, limit, offset, total}), per-profile contents (immutable version, declarations, consent receipts), and possible error types. This adds substantial value over annotations alone.

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

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

The description is compact and front-loaded with the main purpose in the first sentence. Subsequent sentences add distinct value—return structure and errors—without redundancy or fluff.

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

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

With rich parameter schemas, an output schema, and a readOnly annotation, the description adds sufficient context about ordering, response contents, and error cases. It is fully adequate for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, with each parameter having a detailed description. The description only echoes limit/offset in the return shape, adding no new parameter semantics beyond the schema. 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 verb ('List'), the resource ('current creator-profile versions'), and a distinguishing trait ('newest changed first'). This effectively differentiates it from sibling tools like create_creator_profile or get_creator_profile.

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

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

The description provides clear context for use ('Free; read scope', listing versions) but does not explicitly name alternatives or exclusions. The appropriate use case is strongly implied rather than explicitly contrasted with siblings, so it misses a 5.

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

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

Beyond the readOnlyHint annotation, the description adds cost (Free), data retention (90 days), error types (unauthorized, invalid_request, rate_limited), and the return shape. It does not contradict annotations. The limit discrepancy is noted but belongs to parameter semantics.

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 paragraph, front-loaded with purpose, then a dense list of args and return/error info. Every sentence earns its place without 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 9 parameters and output schema, the description covers cost, retention, errors, and return structure. It is nearly complete, but the limit inaccuracy (1-100 vs schema's 1-200) creates a gap in reliable context, so not a 5.

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

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

Schema coverage is 100% with rich descriptions, so baseline is 3. The description summarizes parameters, but it incorrectly states 'limit (1-100)' while the schema allows 1-200. This active misinformation about a parameter range reduces trust and scores below baseline.

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

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

The description starts with "List the hooks this account has bought, newest first," which is a specific verb+resource+scope statement. It clearly distinguishes from sibling tools like get_hook (single hook) and generate_hooks (creation).

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 useful context: 'Free (WP-G)' and 'Retrievable for 90 days.' It implies when the tool can be used, but does not explicitly compare against alternatives or state exclusions. Despite no explicit alternatives, the context is clear enough for a 4.

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 meaningful behavior beyond that: ordering (newest first), response fields (job_id, status, progress_pct, etc.), pagination semantics, and error types (unauthorized, rate_limited). This enriches the agent's understanding 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 compact and well-structured with labeled Args, Returns, and Errors sections. Every sentence is informative, no fluff, and the main purpose is front-loaded in the first sentence.

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

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

Given the presence of output schema and fully detailed parameter descriptions, the description covers all essential aspects: purpose, response format, error cases, and parameter constraints. It is complete enough 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?

Schema coverage is 100%, with each parameter having detailed descriptions (e.g., limit ceiling behavior, offset paging). The description merely restates parameter names and basic bounds, adding no new meaning beyond what the schema already provides.

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 the specific verb 'List' with the resource 'this account's jobs' and adds 'newest first' and 'summaries without the result blob'. This clearly distinguishes it from sibling tools like get_job, which likely retrieves full job details.

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 by stating it returns summaries without the result blob, implying use for lightweight listing rather than full job retrieval. It does not explicitly name alternatives or say when not to use, but the context 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?

Beyond the readOnlyHint annotation, the description discloses key behavioral details: it returns only prefixes, never the raw key; it provides the exact return object schema including field semantics (revoked_at null for active, spent_today since UTC midnight); and lists possible errors (unauthorized, forbidden, rate_limited). This is rich, non-obvious context that helps the agent understand side effects and constraints.

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 essential action and security constraint, followed by a compact but complete return structure explanation. Every sentence provides actionable information with 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?

Given the simple parameter set and the presence of an output schema, the description goes beyond by explaining ordering, field values, default key naming, and error conditions. It fully equips the agent to invoke the tool and interpret results without guessing.

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 covers the only parameter (api_key) with a detailed description of its fallback behavior, achieving 100% schema coverage. The tool description adds no additional parameter-specific meaning (admin scope is not param-related), so the baseline score of 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 tool's job: 'List this account's API keys as PREFIXES only (never the raw key).' It names the resource (API keys), the action (list), and adds a critical scope distinction ('Admin scope'), distinguishing it from sibling tools like create_key and revoke_key.

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

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

The description implies when to use by stating 'Admin scope' and 'this account's API keys', giving clear context. It does not explicitly compare with alternatives or state when not to use, but the read-only listing purpose is clear from the context and sibling names.

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 useful behavioral details: results are ordered newest first, scoped to the current account, include the feature snapshot, and return {outcomes, limit, offset, total}. It also discloses error conditions (unauthorized, invalid_request, rate_limited), which is valuable context for invocation.

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

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

The description is front-loaded with a strong one-sentence purpose, followed by a structured block of args, return, and errors. It is slightly redundant ('List' versus 'Retrieve submitted telemetry') and includes the unclear 'Free (WP-LIFE)', so it isn't perfect, but it remains compact and organized for a tool with six parameters.

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 (six optional parameters, pagination, output schema), the description covers the essential operational context: account scope, ordering, bulk retrieval, return shape, authentication via api_key/headers/env var, and error cases. The presence of an output schema means detailed return field documentation is not required in the description.

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

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

The input schema already covers all parameters with rich descriptions, so the baseline is 3. The description lists the parameters and some constraints (platform enum, since ISO timestamp, limit 1-200, offset >=0), but this largely repeats schema information without adding significant new meaning.

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

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

The description opens with a specific verb+resource+scope: 'List the posted outcomes THIS account has reported, newest first.' This clearly identifies the operation and its account-specific scope, and it distinguishes list_outcomes from sibling list tools like list_hooks or list_runs.

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

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

The description gives clear context for use ('Retrieve submitted telemetry in bulk') and notes the tool is free. It does not explicitly name alternatives or exclusion criteria, but the purpose is sufficiently clear that an agent can infer when to use it versus other listing tools.

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 discloses free/no-charge behavior ('Free read', 'never re-charged'), ordering ('newest first'), pagination semantics ('stop only when exhausted is true, never on a short page'), and consistency with the composed GET /v1/runs. It even lists error types. This is rich behavioral context above 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 compact yet information-dense: opening with the core purpose, then a practical recovery flow, paging rule, consistency guarantee, and error list. Every sentence serves a distinct role 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?

Given the 7 parameters are fully explained in the schema and an output schema exists, the description covers all necessary behavioral context: purpose, safety (free read), paging, error types, and a recovery workflow. It leaves no critical ambiguity for invocation or interpretation.

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

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

The input schema already contains detailed descriptions for all 7 parameters, so the baseline is 3. The description adds a bit by tying request_id to the lost-response recovery flow and cursor/offset to paging, but it does not add significant meaning beyond what the schema provides.

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 'Every call this account was charged for, newest first' — a specific verb+resource+scope that clearly distinguishes this from list_hooks or list_billing_events. It also states 'Free read' and the primary use case (recovering lost responses), making the tool's 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?

Provides a concrete use case: 'Recover a lost response in two calls... list_runs(request_id=...) for the receipt, then follow hooks_url'. Also gives paging instructions with cursor/offset and the exhausting condition. However, it does not explicitly contrast with sibling tools like list_hooks or list_billing_events, nor state when not to use it.

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

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

Beyond the readOnlyHint annotation, the description adds critical behavioral details: 'Free read (WP-HOOKS)', 'payload_preview (200 chars; the full body is never returned)', 'Dead rows are kept 7 days', and a list of possible errors. These disclosures go well beyond what annotations provide and help the agent set expectations.

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

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

The description is front-loaded with the one-sentence purpose, followed by a compact paragraph of usage, args, output fields, retention, and errors. The args summary is somewhat redundant given the rich schema, but it is brief and doesn't bloat the text. Overall well-structured and 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's complexity, the existing output schema, and the readOnlyHint annotation, this description covers all essential aspects: purpose, when to use, key output fields, important limitations, retention, and possible errors. Nothing critical is missing, and the presence of an output schema means the description needn't detail return values further.

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 description coverage is 100% and each parameter already has detailed semantics (e.g., status enum, limit bounds, offset pagination, api_key fallback). The description's 'Args:' line merely restates parameter names and basic ranges, adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'List this account's webhook deliveries, newest first' — a specific verb, resource, and ordering that clearly distinguishes this from sibling tools like list_hooks and get_webhook. The scope ('this account's') and the delivery-specific focus make 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?

It provides explicit context: 'Verify your receiver end-to-end (a webhook.test ping is enqueued at registration) and diagnose failures without waiting out a real event.' This tells the agent exactly when this tool is useful. It does not explicitly name alternatives, but the use case is clear enough and the sibling list reinforces differentiation.

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 goes beyond by stating 'Free, no auth' and detailing the dynamic nature of usd_per_credit (0 while credits are free), plus the exact charge formula. This adds meaningful operational context not available from annotations alone.

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

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

The description is compact but information-dense. Each sentence adds value: identifies the resource, states free/no auth, lists return fields, and explains the charge formula. It is front-loaded with the core purpose, though the return structure could be 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 this is a simple zero-parameter read operation with an output schema, the description is fairly complete. It covers the return shape, the meaning of key fields, and the exact formula. Minor omissions like response envelope are not critical for a static price list.

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, there is nothing to document beyond the schema. The description enhances understanding by explaining the return structure and formula, which helps the agent interpret what the no-arg call returns, going beyond the output schema's type information.

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

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

The description clearly identifies the resource as the machine-readable price list and states it returns pricing constants, which distinguishes it from action-oriented siblings by indicating it contains the exact constants the charge path uses. However, it lacks an explicit verb like 'get' or 'retrieve', relying on 'Returns' to imply read behavior.

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

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

No explicit when-to-use or alternative tools are named. The description implies this is the canonical source for pricing constants via 'exact constants the charge path uses', but does not contrast with similar tools like quote or get_estimates. Thus usage guidance is present but not 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 crucial behavioral context: the operation is free, 'nothing is reserved,' credits_max is a ceiling with payment per hook returned, and `blocker` spells out affordability limits including daily caps. It also lists exact error types (unauthorized, invalid_request, rate_limited). This significantly enriches the agent's understanding of side effects and constraints beyond a simple read-only flag.

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 moderately long but well-structured: a one-sentence summary followed by a compact paragraph of key behaviors. Bolded terms like `credits_max` and `blocker` aid scanning. Every sentence adds information—pricing, validation, errors—without fluff. It earns a 4 rather than a 5 only because the information density is high and slightly verbose, but it remains efficient and front-loaded.

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

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

With an output schema present, the description correctly avoids detailing return values. It covers all operational aspects needed: cost implications (free, nothing reserved), validation consistency with generate_hooks, affordability checks via `blocker`, and error conditions. The readOnlyHint annotation plus these details makes the tool fully understood in context, especially given the complexity of pricing modes.

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

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

The input schema already provides 100% description coverage, so the baseline is 3. The description adds value by clarifying the financial semantics of credits_max (a ceiling, pay per hook returned) and explaining that mode=auto resolves to smart/instant depending on key configuration. This complements the detailed schema mode description and justifies a 4.

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 'Price and time a generate BEFORE you commit to it, without spending,' which clearly identifies the tool as a pre-flight quote for the generate operation. It distinctly separates itself from generate_hooks by stating 'Same validation as generate_hooks' while being free and non-committal. It also lists what it answers (engine, credits_max, expected_wait, affordability), giving a precise verb+resource 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?

The description explicitly says 'BEFORE you commit to it' and 'without spending,' indicating when this should be used. It also notes that mode=auto resolution happens here, which is a specific use case. However, it does not name an alternative tool for when NOT to use (e.g., when you are ready to commit, use generate_hooks directly), so it lacks a full exclusion statement.

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 full burden. It discloses the state reset, admin scope, validity constraints, error responses, and the re-attempt/dead-letter behavior. This is thorough and adds significant context beyond the schema.

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, front-loaded with the core purpose, and every sentence provides necessary detail. It efficiently uses a paragraph for constraints and a bullet-style list for errors, avoiding 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 presence of an output schema, the description doesn't need to detail return values, but it still covers all essential context: prerequisites, constraints, behavior, and errors. It is complete for a mutation tool with no annotations.

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 both parameters thoroughly. The description lists 'Args: delivery_id ... , api_key' but adds minimal new meaning beyond what the schema provides, though it does note the source of delivery_id and the auth fallback behavior for api_key already in 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's purpose with a specific verb and resource: 'Requeue a dead-lettered webhook delivery: reset to pending, due now.' It also distinguishes from siblings by focusing on the redrive action for dead deliveries, which 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 provides explicit when-to-use and when-not-to-use conditions: 'Valid ONLY on a `dead` delivery' and specifies 409 conflict for other statuses. It also gives context about ownership and re-attempt behavior. However, it does not explicitly name alternative tools, though it references list_webhook_deliveries as the source for delivery_id.

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 carries full burden and does well: it discloses determinism, billing ('2 credits per variant,' 'billed only for variants returned'), error types, and the return envelope. It does not mention whether remixes are persisted or if the original is modified, but the return structure implies non-destructive behavior.

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

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

The description is front-loaded with the purpose, then compactly lists args, behavior, returns, and errors. It is dense but every sentence adds useful information. The use of a structured list makes it scannable.

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 an 11-parameter tool with an output schema, the description covers billing, determinism, errors, and return fields. The omission of `topic` and `platform` from the arg summary is a minor completeness gap, but otherwise it is quite comprehensive.

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 baseline is 3. The description adds the useful 'EXACTLY one of text or hook_id' and the alias handling, but its 'Args:' list omits `topic` and `platform`, which is a noticeable gap. It does not significantly enhance the schema details.

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

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

The description opens with 'Rewrite an existing hook into a target archetype,' using a specific verb (rewrite) and resource (existing hook) with a clear target. This clearly distinguishes it from siblings like generate_hooks (create new) and score_hook (evaluate).

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 clear context: this tool is for rewriting an existing hook, and it states the required argument constraints (EXACTLY one of text/hook_id; target_archetype or alias). However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that data is unverified, not consumed by other functions, retained for calibration, and has no prediction power. It also states rate limits (20/hook, 500/day), duplicate conflict behavior, and a concise list of possible errors, giving clear expectations about the tool's behavior.

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

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

The description is a dense paragraph but well-organized, opening with the primary purpose, then the data caveat, a compact parameter list, limits, and return/error summary. Every sentence provides necessary context, though formatting could be improved with line breaks for easier scanning. Appropriately sized for a 9-parameter tool with no annotations.

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

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

Given the tool's complexity (9 parameters, no annotations) and that an output schema exists, the description covers all critical non-schema context: the post-posting use case, data trustworthiness, lack of immediate consumption, rate and conflict rules, and expected return payload. It is thorough enough for an agent to decide when and how to invoke it.

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

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

The input schema already describes every parameter with detailed explanations (100% coverage), so the description adds little beyond listing the parameter names and a few inline comments like '(tiktok|instagram|youtube|x|linkedin|other)'. The high schema coverage sets the baseline at 3; the description doesn't meaningfully augment the schema's semantics.

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 'Report what a bought hook actually did once posted,' which clearly states the action (report) and the resource (outcome of a bought hook). It distinguishes itself from siblings like score_hook and generate_hooks by emphasizing it reports actual results rather than predicting or generating.

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 that data is 'caller-supplied, unverified, and not used by generation/scoring/retrieval today,' clarifying it is for future calibration, not immediate use. This implies when to use it, though no explicit alternatives are named. It could be stronger with a direct 'use list_outcomes to view reported outcomes,' but it provides enough context to guide selection.

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 substantial behavioral context: revoking is idempotent, it requires a DIFFERENT active key for authentication, it returns a specific object, and it enumerates error conditions (unauthorized, forbidden, invalid_request for last key, not_found, rate_limited). This fully discloses the tool's behavior and side effects.

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 compact block with all essential information: purpose, args, return, constraints, and errors. While it's somewhat dense, every sentence contributes; it could be structured with bullets for easier scanning but remains 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's complexity (revoking access), the description covers all necessary context: return format, error types, admin scope, last-key restriction, and authentication fallback. With an output schema present, it doesn't need to explain returns in more detail. It is fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance beyond the schema by specifying that prefix comes from list_keys and is NOT the plaintext key, and that api_key must be a DIFFERENT active key. This enriches parameter understanding.

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

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

The description opens with a specific verb and resource: 'Revoke the key with `prefix`' and immediately clarifies the effect ('it stops working, others keep working'). This clearly distinguishes it from sibling tools like create_key or list_keys, and references list_keys as the source of the prefix.

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

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

Explicitly states when to use: 'Use to kill a leaked or old key.' It also provides a key exclusion ('You cannot revoke your LAST active key (create a replacement first)') and notes the required admin scope, giving clear context for appropriate 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?

With no annotations, the description carries the full transparency burden and exceeds expectations. It discloses deterministic behavior, a fixed credit cost, idempotency replay without re-charging, that text is never persisted as owned, that verbosity only shapes the response, and lists potential error types. This is rich 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 front-loads purpose and cost in the first sentence, then uses a compact structured list for arguments, returns, and errors. It is dense but well-organized; each sentence contributes concrete information without fluff.

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

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

Given a fully described input schema, an output schema, and 7 parameters, the description covers the tool's purpose, key behavioral traits, return envelope, and error cases. It omits only explicit alternative guidance (e.g., when to prefer score_hooks_batch), but overall it is contextually 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 100%, with detailed per-parameter descriptions already present (e.g., topic, verbosity, idempotency_key). The description's parameter summary is a condensed recap and adds little beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'Score any hook text on 5 dimensions with rewrite tips.' It also distinguishes itself as a 'Deterministic heuristic scorer (no LLM)', which separates it from generation tools. However, it does not explicitly differentiate from the sibling score_hooks_batch, so it is clear but lacks explicit sibling differentiation.

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

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

The description provides clear context for when to use the tool: 'Score any hook text' and mentions that passing the same topic as generate reproduces generate's score. It does not explicitly state exclusions or name alternative tools (e.g., score_hooks_batch for multiple hooks), so the guidance is context-rich 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.