VHGENGINE

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

Beyond the idempotentHint annotation, the description details idempotency semantics (replay does NOT grant twice, idempotency_conflict), enumerates specific error types (unauthorized, invalid_request, rate_limited), and specifies the return shape ({credits, granted}). This is substantial behavioral disclosure exceeding what annotations 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 compact and well-structured: purpose and range in the first sentence, followed by deployment-dependent auth behavior, idempotency, return value, and error cases. Every sentence adds unique information with no 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?

Given the tool's complexity (conditional auth, idempotency, error handling, return output), the description covers all essential aspects: admin key conditions, idempotency mechanics, error categories, and response format. The detailed parameter schema and output schema fill any remaining gaps, making it 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?

The input schema already covers all four parameters with descriptions (100% coverage), meeting the baseline. The description enriches the semantics of idempotency_key (replay behavior) and admin_key (conditional requirement), adding value beyond the schema.

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

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

The description clearly states a 'Compatibility credit grant' with a 1-10000 range, identifying the action and resource. It also adds context about beta operations being free. However, it does not explicitly differentiate from sibling billing/usage tools, so it lacks explicit sibling comparison.

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 usage context: admin_key is required when the deployment has VHGENGINE_ADMIN_KEY configured, and the tool stays self-serve otherwise unless free credits are disabled. It also implies limited use during beta since operations are already free. No explicit alternatives are named, but the conditions are well specified.

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?

Beyond the idempotentHint annotation, the description thoroughly explains idempotency behavior ('creates or replays one durable order... retry never mints a second order or session'), the disabled state during beta, and lists possible errors. It reinforces the annotation 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 structured with a clear opening line stating purpose, followed by a paragraph on idempotency, a compact argument list, return format, and error enumeration. It is efficient, though the run-on style of the first sentence 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?

The description covers all critical aspects: expected inputs (including required idempotency_key), behavioral guarantees (idempotent replay), return format (though output schema exists), error scenarios, and a current operational constraint (disabled during beta). It is complete for a checkout-creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal value by referencing 'pack (from pricing.credit_packs)' and noting api_key as 'spend', but the individual parameter descriptions in the schema are already detailed. No significant extra meaning is provided.

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 obtains a hosted-checkout link, with 'Get a hosted-checkout link outside beta' acting as a specific verb+resource. It distinguishes itself from siblings by focusing on checkout creation and explicitly notes a temporary disabled state during free beta 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 implies usage (when you need a checkout link) but does not explicitly state when not to use it or mention alternatives. It does provide context like idempotency and error conditions, but no direct comparison to sibling 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?

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?

No annotations are present, so the description carries the full burden. It discloses that the tool always fails before model, template, provider, storage, or billing work, and enumerates the exact error types (unauthorized; invalid_request with reason unsourced_hook_generation_archived). This is full disclosure of 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?

Four tight sentences that front-load the critical routing instruction ('Use research_hook_evidence instead') and then give failure details. No wasted words.

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

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

For an archived stub that always fails, the description covers the tool's status, the replacement, the fail-fast behavior, and the exact error surface. The extensive schema and output schema are moot because the tool never executes.

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 no per-parameter information, but it implicitly tells agents the parameters are irrelevant by stating the tool always fails. It does not explicitly say 'all parameters are ignored,' which would have pushed this 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?

States the tool is an archived writer and immediately points to research_hook_evidence. The 'Always fails before...' sentence removes any ambiguity about what this tool actually does. It distinguishes itself from the sibling that replaced it.

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 instructs to use research_hook_evidence instead, and states the tool always fails before any real work, so there is no scenario where generate_hooks should be called. The research requirements for the alternative give the agent actionable next steps.

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 burden, and it is extremely transparent: it always fails, it cannot generate or paraphrase hooks, and it specifies the exact error conditions (unauthorized; invalid_request with reason unsourced_hook_generation_archived). This fully discloses the tool's behavior without relying on 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 four sentences, front-loaded with 'Archived' and the redirect. Every sentence serves a purpose: deprecation status, alternative tool, failure behavior, and specific errors. There is no redundancy or unnecessary detail, making it optimally concise.

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 that the tool is archived and always fails, the description is complete: it tells the agent to use research_hook_evidence and exactly what happens if called. The extensive schema and output schema are irrelevant for a tool that never performs work, so the description fully covers the operational 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?

The schema has 100% description coverage, so the baseline is 3. The description adds no parameter-level information, but since the tool always fails, parameter semantics are irrelevant. The schema itself thoroughly documents all 24 parameters, so the description does not need to compensate.

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 labels the tool as an 'Archived source-free batch writer' but does not explicitly state that it generates hooks, which the name implies. It lacks a specific verb+resource and is essentially a restatement of the tool name with a deprecation status. The term 'batch writer' is vague and does not clearly distinguish its original function beyond what the name already conveys.

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 explicit guidance: 'Use research_hook_evidence instead' and states that the tool always fails before any work, so there is no valid use case. It also lists possible errors, making it clear that agents should not call this tool under any circumstances and should use the named alternative.

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 readOnlyHint annotation: it notes that rate_limit mirrors the X-RateLimit-* headers, that the call consumes one unit, that no API key is echoed back, and it lists possible errors. This gives the agent a clear picture of side effects and security behavior.

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

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

The description is compact and front-loaded with the purpose. Each sentence adds value: the budget structure, the pacing guidance, the cost warning, the security note, and the error list. The code block for rate_limit is a concise structured explanation.

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 output schema exists, the description need not enumerate return fields. It covers errors, rate-limit behavior, and security. The tool is simple with one optional parameter, and the description is complete enough for an agent to invoke correctly without surprises. No further context is needed.

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 fully describes the optional api_key parameter with its fallback behavior. The description adds only a note that the API key is never echoed back, which is a behavioral guarantee rather than parameter semantics. With 100% schema coverage, 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 verb and resource: 'Return this account's state + remaining rate-limit budget.' It clearly distinguishes this from sibling read tools like get_usage or get_activity by focusing on the account's own state and rate-limit budget. The first sentence is direct 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 for when to use this tool: to check the rate-limit budget before running a fleet, and it warns that this read itself consumes a rate-limit call. It doesn't explicitly name alternative tools for other purposes, but the guidance is sufficient to understand its typical use case.

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?

Beyond the readOnlyHint annotation, the description discloses account scoping and the deliberate not_found behavior for foreign ids ('no existence leak'), the terminal status semantics, the fixed error set (unauthorized, not_found, rate_limited), and the shape of the success payload. That is materially more than the annotations 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?

Front-loaded one-line summary, then a tightly packed block covering the polling loop, authorization model, return shape and errors. No filler sentences; every clause carries new information.

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

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

An output schema exists so return values need not be re-explained, yet the description still summarizes the payload and error envelopes. Combined with annotations and full schema coverage, an agent has everything needed to call and interpret this 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 job_id, api_key and result_view are already fully documented in the schema. The description adds no parameter-level detail beyond what the schema states, so the 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 first sentence gives a concrete verb and resource ('Poll an async job') plus the exact payload fields returned, so the agent immediately knows what the tool does. However, it never contrasts itself with the obvious sibling alternatives wait_for_job and list_jobs, which is the differentiation a 5 requires.

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?

Clear context is given: poll repeatedly using the returned poll_after_seconds until the status is 'succeeded' or 'failed'. Ownership rules are also stated. What is missing is the routing decision against wait_for_job (which presumably blocks server-side rather than requiring the caller to loop).

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 'Free, no auth' and details the exact return structure (what_this_is, five_steps, modes, wait_guidance, links). This provides behavioral context without contradicting annotations. It could mention rate limits or error behavior, but for a read-only quickstart, the disclosure is sufficient.

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: the first sentence states the purpose, the second outlines the return structure. Every sentence adds value—no fluff or repetition of the schema.

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

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

For a zero-parameter quickstart tool, the description fully covers what it does, what it returns, and the access requirements (no auth). The output schema exists, but the description's breakdown of the return object is still useful and 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?

The tool has zero parameters, so the baseline is 4. The description focuses on the return value, which is appropriate. No additional parameter explanations 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 identifies the tool as a '5-step agent quickstart' with specific content areas (modes, wait guidance, links). It distinguishes itself from sibling tools by focusing on onboarding, and explicitly states what it returns. This is a specific, actionable purpose rather than a vague one.

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 the tool (for getting started and understanding modes/wait guidance), and it notes 'Free, no auth' to set expectations. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to recognize this as the onboarding tool.

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

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

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 says 'DB read+write probe' and 'status is ok only when the DB reads and writes,' implying the tool performs database writes. This directly contradicts the annotation readOnlyHint=true, making the behavioral disclosure unreliable. Annotation 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 core purpose is front-loaded and the description is dense with useful details. The enumerated return-field list and overlap with the 'same probes as GET /health' phrasing make it slightly heavier than necessary, but most content 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?

With an output schema present and no parameters, the description goes beyond the minimum by explaining readiness vs codec support, source writer state, and the job_worker_alive caveat. However, the readOnlyHint contradiction means a key behavioral aspect is not reliably communicated.

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?

This tool has zero parameters and schema description coverage is 100%, so no parameter-level meaning is needed. The baseline of 4 applies because parameter semantics are trivially satisfied.

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 immediately identifies this as a deep health probe covering DB read/write, worker/queue, backup, and integrity, and clarifies the status semantics ('ok' only when the DB reads and writes). This clearly distinguishes it from sibling tools like get_job or wait_for_job.

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 operational context by referencing GET /health probes and gives an explicit cross-tool instruction: check job_worker_alive before start_generate_job. It does not enumerate when not to use this tool, but the usage context is otherwise 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 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 already declare readOnlyHint=true, which reduces the burden. The description adds valuable context beyond that: it specifies that no authentication is required, that all operations are currently zero-priced, describes the response structure ({unit, usd_per_credit, beta, operations, pricing_modes...}), and notes that internal provider-credit ceilings are separate. This enriches the agent's understanding without contradicting the read-only hint.

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 concise and well-structured, containing multiple purposeful sentences that each add information (purpose, auth/free status, beta pricing, response shape, and a caveat about internal ceilings). It is not as tight as a two-sentence ideal, but it avoids redundancy and earns its length for a tool that carries behavioral context.

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, a read-only annotation, and an output schema exists, the description fully covers the remaining context: what the list is, its auth requirements, current pricing, the exact return fields, and a caveat about internal ceilings. This is complete for an agent to safely decide to call and interpret 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?

The tool has zero parameters, and the schema coverage is 100% (the schema is empty). Per the rubric, a baseline of 4 applies for 0-parameter tools. The description adds no parameter-level detail because none exists, but it does clarify the nature of the returned data, which is the only semantic aspect of interest here.

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 this as 'the machine-readable price list' with a specific scope ('per-mode expected_wait'). It distinguishes itself from sibling tools like quote or get_estimates by framing itself as the authoritative list rather than a dynamic estimate, and the 'Free, no auth' note further clarifies its role as a safe, public reference.

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

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

The description provides context about when this tool is appropriate (free, no auth, zero-priced during beta) and hints that it is the canonical price reference. However, it does not explicitly state when not to use it or mention alternatives (e.g., quote for specific estimates), leaving the when-to-use guidance somewhat 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?

Annotations only indicate readOnlyHint=true, while the description adds substantial behavioral details: it validates the retained input schema, computes historical price ceiling, balance, cap blocker, and wait metadata, and stresses that no billing occurs. It also specifies possible errors (unauthorized, invalid_request, rate_limited), which is beyond the annotations. No contradiction.

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

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

The description is short, front-loads the purpose in the first sentence, then adds necessary limitations and error details. Each sentence contributes value without redundancy, making it highly concise and well-structured.

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

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

Given the output schema exists (the agent can infer return values) and the description covers purpose, limitations, and errors, the tool is adequately specified for an agent to invoke it correctly. The only minor gap is not explicitly naming sibling pricing tools, but the overall context is complete enough.

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?

All six parameters have rich descriptions in the input schema (100% coverage), including defaults, enums, and constraints. The main tool description does not add any additional parameter-specific meaning beyond saying it validates the retained input schema, so a 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 a specific action and resource: 'Read archived generation price and wait metadata without spending. Free.' It further clarifies that it computes historical price ceiling, balance, cap blocker, and wait metadata, and explicitly distinguishes itself from generate_hooks by noting that tool is archived and always fails. This leaves no ambiguity about the tool's function.

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 that this is a free, read-only historical quote tool for an archived generator. It explicitly says it does not authorize or predict a runnable operation, which implies it should not be used for live generation, but it does not name alternatives like get_estimates or pricing. Thus there is clear context but no explicit when-not-to-use vs those 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?

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 provided, the description carries the full burden and discloses that the tool always fails before any work, never charges, and returns specific errors ('unauthorized; invalid_request with reason unsourced_hook_generation_archived'). This is fully transparent regarding the tool's guaranteed failure.

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

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

Four short sentences front-load the core facts (archived, fail, alternative) and then list the error conditions. Every sentence serves a purpose with zero wasted words.

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

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

Given that the tool always fails, the description fully covers behavior, errors, and the recommended replacement. The output schema exists, so return-value details are unnecessary. The context is complete for any agent evaluating 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 already provides exhaustive descriptions for all 11 parameters (100% coverage), so the tool description does not need to add parameter-level detail. The description adds no parameter-specific semantics, but the schema fully compensates, so the baseline of 3 applies.

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

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

The description immediately establishes the tool as an 'Archived source-free remix writer' and states it 'Always fails before rewriting, model, storage, or billing work.' This clearly signals it is a deprecated, non-functional tool and differentiates it from the recommended research_hook_evidence alternative.

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 instructs the agent to 'Use research_hook_evidence instead' and notes the tool 'Always fails,' making it unambiguous that this tool should never be invoked. The alternative is named, and the failure behavior is stated up front.

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?

With no annotations, this description fully carries the behavioral burden. It discloses side effects (spends credits), timeouts (600-second authorization), error semantics (502 meaning), idempotency guarantees, async job behavior, result_view effects, and error types. This is far beyond what structured fields 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 dense and information-rich, with every sentence contributing, and it is front-loaded with the purpose. However, it is a single long paragraph with no bullets or breaks, making it harder to scan. Given the high complexity, the size is justifiable, but the structure could be improved.

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 is remarkably complete: it covers operational behavior, error handling, timeouts, async job flow, idempotency, result views, and even output item fields like first_audible_speech. An output schema exists, so return-value detail is not needed. For a complex 26-parameter tool with zero annotations, this is sufficient 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%, so the baseline is 3. The description adds meaningful semantics for key parameters: allow_partial ('accepts a shortfall at or above the declared minimum'), idempotency_key (replay for completed result, no extra charge), result_view (compact vs full), and requested_count thresholds. This exceeds the baseline without duplicating every schema 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 action and resource: 'Return an unpadded portfolio selected deterministically from verified evidence.' This clearly conveys the tool's core function. However, it does not explicitly contrast it with sibling tools like generate_hooks or synthesize_hooks, so it is clear but not maximally differentiating.

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 concrete situational guidance: when to use sync vs async ('Counts 11-30 require an idempotency key and return a durable job; poll get_job'), when allow_partial applies, and how to handle a 502 via idempotency_key replay. It references sibling get_job for follow-up but does not broadly compare against all sibling tools, so it stops short of a full alternative-routing guide.

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