Hook Detector

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

With no annotations provided, the description fully carries the disclosure burden and does so well. It states owner-only authorization, the HTTP method, exact failure semantics (422 credits_below_zero and 404 account_not_found), that nothing changes on failure, that changes are audited, and the response shape. This is exemplary transparency for a mutation tool.

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

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

The description is compact and front-loaded, opening with the action and owner restriction before covering errors, audit behavior, and return shape. Each of the four short sentences adds operational value 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?

The description is broadly complete for a mutation tool: ownership, endpoint, error semantics, audit side effect, and return shape are all covered. Minor gaps are the undocumented api_key parameter and the 'required' note inconsistency, but the output schema and sibling references cover most of the remaining context.

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

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

Schema coverage is 75%, so note, delta, and account_id are already described in the schema. The description adds little per-parameter meaning beyond reinforcing delta's add/remove behavior and the error cases. It does not clarify the undocumented api_key parameter, and it leaves unresolved the inconsistency between the note's 'required' text and the schema marking no parameters as required.

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

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

The description names a specific action (add or remove credits), the resource (an account's credits), and the explicit REST endpoint. It also marks the operation as owner-only, which clearly separates it from the read-only admin listing siblings. There is no ambiguity about what this tool does.

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

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

The description gives clear context: it is an owner-only mutation, and it references admin_list_actions as the audit trail for changes. It does not explicitly state when to prefer this tool over read-only siblings or provide when-not-to-use conditions, but the intended use case is strongly implied.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the permission requirement ('Owner only'), the ordering ('newest first'), the response structure (including all fields), and the HTTP endpoint. This goes beyond a minimal template. It does not explicitly state read-only or idempotency, but the nature of a list operation and the response format strongly imply non-destructive. The 'Free' note likely indicates no cost tier implications, adding a practical behavioral detail.

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

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

The description is a single, dense sentence that packs the endpoint, permission, ordering, and full response shape with zero fluff. It front-loads the most crucial constraints ('Owner only', 'every account, newest first') before the technical details. Every part serves a purpose, making it highly efficient.

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

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

The description is largely complete for a list tool: it specifies the endpoint, the permission, the ordering, and the response fields. The output schema is present, so return structure is further documented. However, it omits mention of pagination (limit/offset) semantics, the api_key parameter, and error handling. While not critical for basic invocation, these are relevant for a robust caller, so a small gap remains.

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 covers q, limit, and offset with descriptions (75% coverage), so the description need not repeat them. The api_key parameter lacks a schema description, and the tool description does not compensate by explaining it. The description does not add any additional meaning to the parameters beyond what is in the schema—it seems to focus on the response format. Thus, while baseline is 3, the lack of compensation for the undocumented api_key prevents a higher score.

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

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

The description states a specific action ('list accounts'), a specific resource ('admin/accounts'), and the ordering ('newest first'). It clearly differentiates from sibling admin tools (like admin_list_actions or admin_list_runs) by the resource being accounts. The 'Owner only' guard also clarifies the audience, making the purpose unmistakable.

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

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

The description provides a clear usage condition: 'Owner only'. It implies this is for administrative listing of all accounts, which contrasts with other tools focused on actions or runs. It does not explicitly mention alternatives or exclusions, but the 'Owner only' is a strong usage guideline. The mention of 'every account' also signals when a broad listing is intended, though the optional 'q' parameter for filtering is not described in the text.

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. It discloses access restriction ('Owner only'), the read-only nature implied by 'GET', sort order ('newest first'), price ('Free'), and the returned field shape. It does not mention rate limits or pagination details, but for a read-only audit listing this is reasonably transparent.

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

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

A single dense sentence with no filler. It front-loads the access restriction, then states the resource, endpoint, response shape, and cost. Every element adds value and nothing is redundant.

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 output schema already covers return values, so the inline response shape is redundant but harmless. The description covers purpose, access, ordering, and pricing. The main gap is the unexplained api_key parameter, and no alternative-tool guidance is given, but for a simple read-only list tool the definition is nearly complete.

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

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

Schema coverage is only 50% because limit has a description but api_key does not. The tool description does not explain api_key at all, nor does it add meaning to limit beyond the schema. Since schema coverage is low, the description should compensate for the undocumented parameter but fails to do so.

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: listing the audit of password sign-ins and credit changes via GET /v1/admin/actions, newest first. This clearly distinguishes it from sibling tools like admin_list_accounts and admin_list_runs by focusing on the audit log category.

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 'Owner only' prefix gives an explicit access prerequisite, and the data scope ('audit of password sign-ins and credit changes') tells when this tool is relevant. It does not explicitly contrast with sibling admin tools, but the context is clear enough for an agent to choose it for audit-log needs.

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 behavioral burden and does well: it discloses the HTTP method, response shape, ordering, access restriction, and that the call is free. It does not mention rate limits or pagination behavior, but for a read-only admin list the disclosed information is substantial.

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 one tight sentence that front-loads the most important scoping information ('Owner only', 'every account's', 'newest first') and then gives the endpoint and return shape. Every element 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 a well-described input schema, the description is largely complete: it covers access, scope, ordering, endpoint, and response fields. It could add a note about how api_key is used or how pagination works, but these are minor 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?

Schema coverage is 75%, so most parameters are already documented. The description adds no parameter-level detail, and the undocumented api_key parameter is not clarified, but the schema's descriptions for limit, status, and account_id are sufficient.

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

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

The description states a specific verb ('list'), a clear resource ('every account's research runs'), and a distinguishing scope ('Owner only'). It also names the exact endpoint and sort order, so an agent can clearly tell this admin tool apart from the user-level list_runs sibling.

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

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

The description gives clear context: this is for owners and returns runs across all accounts, newest first. It does not explicitly name an alternative or state when not to use it, but the 'Owner only' and 'every account's' phrasing makes the intended use obvious.

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 so thoroughly. It discloses the HTTP method (GET), access requirements (admin scope/account), the 403 error condition, the free cost, and the null-when-unread behavior for search fields.

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 front-loaded with the most important facts (owner-only, overview, endpoint). Every clause adds value—auth, error, cost, and field groups—without filler or redundant restatement of the tool name.

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

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

For a single-parameter tool with an output schema, the description covers the authorization condition, error case, cost, and the semantic meaning of all returned data groups. The output schema supplies the detailed return shape, so the description is complete enough 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?

The description adds no meaning about the single api_key parameter, and schema description coverage is 0%. The auth requirement implies the key must belong to an admin account, but the description never explains how api_key relates to the call or its default-null optionality.

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

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

The description names the exact resource and operation ('the whole service at a glance, as GET /v1/admin/overview') and enumerates the aggregate data it returns. This clearly distinguishes it from sibling list/detail tools like admin_list_accounts and admin_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: it is the owner-only, aggregate service overview and requires an admin account with the admin scope. It does not explicitly name sibling alternatives or state when not to use it, but the aggregate-vs-list distinction is strongly implied by the field enumeration.

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 excels: it discloses one-use code generation, request marking, emailing, the emailed true/false flag, code visibility only once, revocation on re-approval, and the 409 request_already_decided error. This is exemplary 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?

Every sentence adds distinct, necessary information: ownership, the action, code generation, email status, retry behavior, error handling, and cost. The core action is front-loaded and there is no filler.

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

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

The description covers behavior, errors, cost, and the emailed flag, while the output schema can handle return structure details. The only notable gap is explicit parameter guidance, but for a two-parameter tool with reasonably self-descriptive names this is a minor omission.

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

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

The description never names request_id or api_key, and the input schema has 0% description coverage. The phrase 'approve an access request' implies request_id is the target, but api_key and the exact parameter mapping are left to inference, so the description does not fully compensate for the schema gap.

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 'Owner only: approve an access request,' a specific verb and resource that clearly identifies the action. It also distinguishes itself from siblings like reject_access_request and create_access_code by describing the approval workflow and one-use code.

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 owner-only prerequisite and 'Free' note give some usage context, and the verb 'approve' implies the intended scenario. However, the description never explicitly contrasts this tool with reject_access_request or states when not to use it, so usage guidance is implied rather than stated.

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

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

No annotations are provided, so the description carries the behavioral burden. It says 'Free' and 'right now', implying a non-mutating, no-debit operation, and it lists what data will be returned. It does not explicitly say 'read-only' or cover rate limits and errors, but the core behavior is reasonably disclosed.

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

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

The description is dense and front-loaded, but it is a single run-on paragraph with a long comma-separated list and abrupt clauses like 'Free.' It contains no filler, but the structure could be clearer with bullets or shorter sentences.

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 balance call with an output schema, this is nearly complete: it states what is returned, directs the agent to usage for spend details, and gives credit threshold/reservation context. Minor gaps include explicit auth handling and read-only/error behavior.

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

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

The schema has 0% description coverage for the one api_key parameter. The description mentions 'the key making this call' but does not explain how api_key should be supplied or what null means. Because the description must compensate for low schema coverage definition and does not, this is a gap.

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

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

The description clearly states the tool returns account and remaining credits, and enumerates the response fields. It does not use an explicit verb like 'get' or 'retrieve', but 'Same shape as GET /v1/me' plus the field list makes 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 explicitly routes the agent to a sibling when spend details are needed: 'For spend, credits held by in-flight runs and daily history, call usage.' It also provides the important 40-credit minimum and 200-credit reservation context for running a workflow.

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 behavioral burden and does so richly: cost model (turn is free but a model call, hourly limits, 429 rate_limited), credit reservation behavior for runs, required scopes (write permission plus research, 403 insufficient_scope with nothing reserved), and error semantics (503 model_unavailable nothing charged, 402 insufficient_credits, 422 invalid_request). This is exactly the disclosure a mutation-plus-model-call tool needs.

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?

It is long but front-loads the three actions and their outputs before descending into parameter and error detail, so the reader gets the core model immediately. Some locale content duplicates the language/country schema descriptions, which is mild redundancy rather than wasted space given the tool's complexity.

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

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

Given 10 parameters, a mutation-plus-model-call surface, and an output schema that already documents returns, the description supplies the remaining essentials: action semantics, suggestions shape, next-step call to get_run, credit/permission implications, and error recovery. An agent has everything needed to invoke and follow up 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 70% and the schema itself documents most fields thoroughly, but the description adds genuine meaning beyond it: the precedence rules for deck size (message text beats count, count beats the turn's guess), how language/country persist or clear across turns, and how posted_within_days interacts with a recency phrase. Only minor overlap with schema text keeps it from 5.

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 framing ('One conversational turn, for an agent relaying a person's words') and enumerates the three possible actions (clarify, answer, research) with their distinguishing outputs. It names the sibling tools it is not (find_hooks, remix_hook), so an agent can route correctly without opening other schemas.

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

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

It gives concrete routing guidance: 'For direct research without the question step, call find_hooks instead' and 'on research, call get_run with run.run_id'. It also explains conversation_id semantics (pass to continue, omit to start). It lacks explicit when-not guidance relative to conversational siblings like get_conversation or list_conversations, so it stops short of a full 5.

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

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

With no annotations, the description fully carries the behavioral disclosure burden. It explains side effects on list_keeps and exports, the exact return shape, idempotency, cost, and error cases. There is no contradiction with annotations because none are provided.

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 adds value: purpose is front-loaded, then idempotency, endpoint mapping, cost, and errors each get one clear clause. There is no filler or redundancy.

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

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

For a simple two-parameter mutation with no annotations, the description covers behavior, side effects, retry safety, cost, and errors; an output schema exists so return-value details are bonus. The only notable gap is the unexplained api_key parameter, though its optionality is visible in the schema.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly explains hook_id via the endpoint and the UUID error, but api_key is never mentioned or clarified. With two parameters and one completely unaddressed, the compensation is only partial.

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 'Undo keep_hook', naming the exact operation and resource. It clearly states the effect, the return value, and the equivalent DELETE endpoint, making its purpose unambiguous and distinct from sibling keep_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 provides strong context by identifying this as the inverse of keep_hook and noting that clearing an already-undecided hook is also success, so retries are safe. It does not explicitly list alternatives or when-not-to-use conditions, but the usage intent is clear.

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

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

With no annotations, the description carries the full burden and does a solid job: it discloses the side effects (verdict nulled on every find, removed from list_kept_finds), idempotent/retry-safe behavior, and cost ('Free'). It omits auth requirements (the api_key parameter) and any error behavior, keeping it short of a 5.

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

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

Front-loaded with the core action, then return value, idempotency, HTTP equivalence, and cost in four lean sentences. The trailing one-word 'Free.' and the HTTP-path aside are slightly non-essential but not wasteful enough to hurt usability.

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 re-explaining the return value is bonus rather than required. Combined with the disclosed side effects, idempotency, and cost, the definition is nearly complete; the only real gap is the undocumented api_key parameter and lack of differentiation from clear_decision.

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

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

Schema coverage is 0% for two parameters, so the description must compensate. It contextually identifies find_id via the return shape and the per-find semantics, but says nothing about api_key or the required/optional distinction. Half the parameters remain undocumented in both places.

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 gives a specific verb+resource pair ('clear' the 'find decision') and anchors it explicitly to the inverse sibling operation ('Undo keep_find'), so an agent can place it precisely in the keep/clear lifecycle. It also states the concrete state change: the video returns to having no verdict on every find and leaves list_kept_finds.

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 clearly frames this as the inverse of keep_find and clarifies that clearing an already-undecided find is a success, which tells the agent it can call this without a precondition check. It does not, however, distinguish itself from the sibling clear_decision tool, 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?

With no annotations provided, the description carries the full burden and delivers: ownership requirement, email binding restrictions (only Google sign-in, not API/MCP), the code appearing only in this result, and cost (Free). This is exceptionally transparent and leaves no critical behavioral ambiguity.

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, with each sentence serving a purpose. It opens with the core action and ownership, then systematically covers parameters and behavioral nuances, ending with cost. No redundancy or 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 tool with 5 optional parameters and an output schema, the description covers most essentials: constraints, defaults, binding behavior, and result handling. The only gap is the unmentioned api_key parameter, and error conditions are not discussed, but overall it 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 0%, so the description must compensate. It explains max_uses (1-100000, default 1), expires_in_days (1-365 optional), note (user-provided), and email (binds to person). However, it omits any explanation of the api_key parameter, which remains undocumented in both schema and 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 explicitly states 'Owner only: make an access code to hand out' with a clear verb+resource, distinguishing it from siblings like list_access_codes and revoke_access_code. The purpose is unambiguous and the ownership restriction is immediately front-loaded.

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 clearly defines when to use the tool (creating a new access code) and provides contextual guidance like 'Owner only' and the email binding behavior. It does not explicitly name alternatives or exclusions, but the use case is obvious and the description gives enough context for an agent to decide.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the returned api_key is the only copy, that signups and wrong codes are rate-limited per address per hour, and that the call requires no prior key. It also explains error behavior (403 access_code_required, 403 invalid_access_code). This is exemplary transparency for a tool with no 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 dense but well-organized, front-loading the core purpose and then covering prerequisites, error handling, and next steps. Every sentence adds value. It could be slightly more structured (e.g., separating the 'keep the api_key' instruction into its own paragraph), but it's appropriately sized for the complexity of 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 is complete for an account creation tool. It covers the purpose, required input, error cases, output handling (api_key), rate limits, and next steps. The output schema exists, so return values don't need to be described in detail. The only thing not covered is the exact response format, but that's provided by the output schema. This is a model description.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the access_code parameter in detail (format HD-XXXX-XXXX, case/dashes don't matter, error codes) and the label parameter (optional note up to 120 characters). The only minor gap is that it doesn't explicitly state that both parameters are optional (schema shows default null), but the description implies access_code is needed and label is optional, which is sufficient.

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

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

The description clearly states the tool's purpose: 'Create an account and get an API key with free credits.' It uses a specific verb and resource, and distinguishes itself from sibling tools like request_access and create_access_code by explaining that this is the account creation endpoint, not an access code request. The mention of 'No key needed for this call' further differentiates it from other tools that require an API key.

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

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

The description provides explicit when-to-use guidance: it requires a beta access code, explains how to obtain one (request_access or hookdetector.com/access), and states the error codes for missing/invalid codes. It also tells the user what to do next (find_hooks) and how to use the returned key in subsequent calls. This is comprehensive 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?

With no annotations present, the description fully carries the behavioral burden and does so thoroughly: the key appears only once, admin is required, quotas are disclosed (10 active keys, 20/hour), expiry produces 401 key_expired, credit reservations are explained, and scope side effects like spending credits are spelled out.

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 every sentence earns its place. Purpose is front-loaded, parameters are grouped into focused clauses, and quotas, auth, and next steps form compact, readable sections. There is no tautology or 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?

This is a complex credential-creation tool with no annotations and no schema descriptions, yet the description covers purpose, defaults, side effects, quotas, errors, auth requirements, and next steps. The output schema covers the return shape, and the description adds the critical storage warning. The only minor gap is the undocumented api_key input parameter.

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

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

The description compensates for 0% schema coverage by explaining name length, all scope values with their meanings and defaults, credit_limit range and behavior, and expires_in_days bounds. However, the api_key input parameter is never explained; an agent is left to guess what it means or whether to provide 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?

The first sentence states a specific verb and resource: 'Create another API key on your account', and gives a concrete motivating use case (one per agent or machine) so an agent can distinguish it from sibling tools like revoke_key or list_keys. The purpose is unmistakable.

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: create separate keys for separate agents/machines, apply least-privilege scopes, and 'Needs admin' sets an important prerequisite. It also points to revoke_key as the next step, but it does not explicitly say when not to use this tool versus alternatives like list_keys or revoke_key.

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 exceeds it. It discloses irreversibility, exactly what data is erased, unspent credits loss, confirmation failure behavior with error code 422, the 409 conflict condition, key invalidation across the account, REST equivalence, and cost. Nothing about the destructive or conditional behavior is left to inference.

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?

Roughly 100 words of dense, high-signal prose. The most critical information (destructiveness, irreversibility) is front-loaded, followed by confirmation requirements, conflict conditions, return format, and side effects. Every sentence earns its place; no filler or repetition of schema fields.

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 irreversible 2-parameter operation with zero annotations and zero schema descriptions, everything an agent needs to call it correctly and safely is present: preconditions (run-in-flight check), exact confirmation value, error codes, side effects, response shape, REST equivalent, and cost. The output schema exists per context, so return values are also structurally covered.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly for confirm — specifying the exact literal value ('delete my account'), the failure mode, and its error code — which is the parameter an agent is most likely to get wrong. The api_key parameter receives no explanation, but its title is self-describing and it defaults to null, so the gap is minor.

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 states a specific verb and resource: 'Erase your account and everything in it, for good,' followed by a concrete inventory of what is destroyed (API keys, runs, hooks, decisions, conversations, messages, unspent credits). This clearly distinguishes it from siblings like revoke_key (key-scoped), clear_decision (decision-scoped), and create_account (creation, not destruction).

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 clear operational context: the exact confirmation string required, the 409 run_in_flight refusal with instruction to wait via get_run first, and mentions create_account as the follow-up for a new account. It lacks a formal when-not-to-use exclusion (e.g., 'for lighter scopes use revoke_key or clear_decision instead'), but 'It cannot be undone' plus the run-in-flight condition gives an agent strong sequencing 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?

No annotations are provided, so the description carries the full burden, and it succeeds. It discloses the fallback behavior, the conditions that trigger it, the thumbnail/still_url/transcript behavior, and the fact that the tool is free.

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

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

The description is dense but efficient, front-loading the main purpose and then covering fallback behavior and the alternative. The fallback clause is somewhat run-on, but every part adds information and there is no filler.

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

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

Given that an output schema exists and the description already explains the important fallback semantics, the agent has enough to select and invoke the tool. The main remaining gap is parameter-level detail, especially api_key, which is notable but not crippling given the small parameter set.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation, but it never explains api_key or hook_id. It provides useful domain context about hooks, player_url, and still_url, yet leaves api_key's purpose and whether it is truly needed ambiguous despite the optional default.

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 deliverable: official TikTok or Instagram embed HTML for a hook, with a clear distinction from the plain iframe path via player_url. It also explains the fallback output mode, so an agent can tell exactly what this tool produces.

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

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

The description gives concrete usage context: use this for official embed HTML, and use player_url instead when a plain vertical iframe is needed. It also spells out when the fallback kind applies, e.g., embedding disabled or an old photo post. It does not enumerate other sibling tools, but the provided alternative is explicitly named.

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

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

With no annotations, the description fully carries behavioral disclosure: it explains the return object, format-specific transformations (csv defusing formulas), the equivalence to the HTTP GET endpoint, that it is free, and all relevant error codes. This goes well 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?

Every sentence carries operational value: formats, return structure, HTTP equivalence, cost, and errors. The description is front-loaded with format details and uses line breaks to separate concerns, with no filler.

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

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

Even with an output schema present, the description adds the complete contract: return keys, content semantics, error cases, and the prerequisite wait behavior. For a tool with one required and two optional parameters, this is thoroughly complete.

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

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

Schema coverage is 0%, so the description must compensate. It richly explains the format parameter ('csv', 'json', 'md') and gives meaning to run_id ('a finished run's hooks'). The api_key parameter is not described, but its role as authentication is reasonably inferable, making this a strong but not perfect compensation.

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

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

The description clearly identifies the resource ('a finished run's hooks') and the action (export as a file), and details the three formats. It distinguishes itself from sibling tools like get_run and get_hook by focusing on the finished-run hooks export 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?

It offers explicit guidance on when not to use it ('while the run is queued or running') and tells the agent to call get_run with wait_seconds=50 first. It also lists format choices, but does not explicitly name alternatives for the export use case itself.

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 behavioral burden and does so: credit reservation and refund rules, failed/no-result runs costing nothing, permission requirements (403 insufficient_scope, key_credit_limit_reached), idempotency window, timing (2-3 minutes, up to 5 for dialects), and the talking-heads-only delivery guarantee. This is unusually complete.

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

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

Front-loaded with purpose and divided into labeled sections, which helps, but it is bloated: repeated 'since 2026-XX-XX' version stamps, restated return fields already covered by the output schema, and duplicated param details. Much of the length earns its place, but it could be trimmed meaningfully.

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

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

Given a 12-parameter async tool with cost, a permission model, and a multi-call lifecycle, the description covers everything an agent needs to call it correctly and to poll to completion. An output schema exists, so return values need not be spelled out, yet the description still maps the key delivered fields.

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 92%, so the schema already documents most parameters. The description does add real semantics beyond it (seed steering behavior, the language judge honoring mixed values 'not measured yet', reuse economics, country/language precedence), but much of the parameter prose mirrors the schema descriptions.

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

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

States a specific verb and resource ('Start hook research on a topic') and scopes the platforms precisely, including the explicit exclusion 'Shorts only, never long-form YouTube'. An agent can tell it apart from find_long_hooks without opening either schema.

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

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

Gives explicit when-to-use guidance for reuse (default true, near-free reruns), idempotency_key (always pass one and reuse it on retry), seed_hook_ids ('find more like these'), wait_seconds, and the required follow-up loop with get_run. It also names the condition that selects the alternative (long-form), leaving little to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does much of that: cost reservation (90 credits for 20 or fewer, 5 per extra), rate limits (429), failure cost (nothing), link-address refusal (422), and reuse semantics. However, it doesn't state whether the operation is safe/read-only versus mutating in a compact way for an agent, and some behavioral edges (retry behavior, concurrency) are omitted. Still very strong for a no-annotation tool.

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

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

This is an extremely long, dense description that mixes purpose, detailed return schema (finds, report fields, outliers), parameters, cost, and timing into one block. It is not front-loaded for quick scanning; a reader must parse many lines of return-shape detail before getting to arguments and next steps. Much of the return-shape detail duplicates the output schema, which is a waste of description budget.

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

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

Given the complexity (13 params, nested output) and the presence of an output schema, the description is very complete, perhaps overly so. It covers link handling, cost, rate limits, and the get_run flow. Completeness is strong, but the inclusion of extensive return-field explanations is redundant when an output schema exists, suggesting the description is compensating beyond need.

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 92%, so the schema already documents nearly all parameters. The description adds meaning to key ones (topic link behavior, min_outlier threshold, reuse, idempotency_key, wait_seconds), which reinforces but largely mirrors schema content. Baseline 3 is appropriate when 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 states a specific verb and resource ('searches YouTube for long-form videos', 'find long-form hooks'), defines the outlier concept, and explicitly distinguishes the scope from siblings: 'Long-form YouTube only, never Shorts, TikTok or Instagram (for those: find_hooks).' This routes the agent to the right tool immediately.

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

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

Explicit when-to-use and when-not-to-use, naming the alternative (find_hooks for Shorts/TikTok/Instagram, remix_find for link-based writing). It also instructs the follow-up pattern (get_run with wait_seconds=50 until done), the idempotency_key usage, and permission requirements. This is far beyond minimum 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?

No annotations are provided, so the description carries the full behavioral burden and does so thoroughly: it discloses cost mechanics (up to 70 credits for ≤24 packages, +3 each above, down to 25; failed/empty runs free), the research-permission requirement, idempotency behavior, progress reporting via progress.items/progress.scan, and that timing is unmeasured so no time should be assumed. It also explains drop/retry semantics for unanalysed packages and that thumbnail inspection costs no credit.

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?

Purpose is front-loaded and the prose is organized into labeled sections, which helps. But it is heavily bloated: the 'What comes back' block enumerates dozens of return fields in prose even though an output schema exists, making it far longer than necessary for an agent that already receives structured output.

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

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

Given a 12-parameter async job with credit costs and a research-permission requirement, the description covers everything an agent needs: cost, timing guidance, polling via get_run with wait_seconds, progress fields, permission needs, and error/refusal cases. It is arguably over-complete, which is not a completeness gap.

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

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

Schema description coverage is 92%, so the schema already documents nearly every parameter; the description mostly restates the same bounds ('count 1 to 30', 'topic 3 to 500 characters') and defers others to find_long_hooks. It adds marginal framing (topic may be a channel or video address, Shorts refused with 422) but does not meaningfully extend beyond the schema, 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?

States a specific verb+resource ('Find packaging: the titles and thumbnails that earned the click') and scopes it to long-form YouTube videos that beat their channel. It explicitly differentiates from its closest sibling by noting it 'runs the same outlier search as find_long_hooks' and then adds the thumbnail/title analysis, so an agent can distinguish the two without opening either schema.

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

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

Gives clear context: it reuses the find_long_hooks search, is 'close to free' after a find_long_hooks run on the same topic, and routes link-based runs to remix_find. However it never states an explicit when-to-use-this-instead-of-find_long_hooks condition beyond the implicit 'you want thumbnail+title analysis', so it stops short of a full when/when-not/alternative statement.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (role, content, run_id, created_at), pagination semantics including when earlier_cursor is null, that the cost is 'Free', and two error codes with their meanings. It omits explicit auth/permission requirements, which is the main remaining gap.

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-loads the resource, then packs pagination, cost and errors into a tight passage. The heavy parenthetical nesting makes it dense, but every clause carries information; nothing is decorative.

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 restating the return shape is partly redundant, yet the description rounds out the picture with pagination behavior and precise error semantics. For a moderately complex read tool with a required id, nothing essential for calling it is missing.

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

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

Schema coverage is only 50% (api_key and conversation_id undocumented), so the description has to compensate. It explains the pagination contract clearly — 'a page of limit' with earlier_cursor for older messages, null at the first message — adding real meaning beyond the schema's terse limit/before descriptions.

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

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

States a specific resource with a clear scope: 'One chat conversation' with its newest messages, runs and settings. The word 'one' implicitly distinguishes it from the sibling list_conversations, though the sibling is never named. Clear enough that an agent knows exactly what it retrieves.

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 only implied by the description of a single conversation lookup; there is no explicit when-to-use, no note to prefer list_conversations to enumerate, and no stated prerequisites. An agent can infer the context but is not guided.

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

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

With no annotations, the description carries the full burden and does well: it discloses cost ('Free'), maps it to an HTTP shape ('Same shape as GET /v1/finds/{find_id}'), and enumerates failure modes (404 find_not_found, 422 for a non-UUID id). It does not cover auth/permission behavior or the fact that api_key may be required.

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

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

Front-loaded with the resource definition, then provenance, then errors, with no filler sentences. The first clause is dense and slightly jargon-heavy ('long or packaging run', 'the opening or the package analysis'), which costs a little clarity for a general reader.

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 described, and the description correctly omits them. It supplies cost, error behavior, and provenance, leaving only auth semantics unaddressed, which is adequate for a two-parameter read tool.

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

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

Schema description coverage is 0%, so the description must compensate. It covers find_id thoroughly, giving its provenance and, via the 422 note, its UUID format constraint. api_key is left entirely unexplained, keeping this from a 5.

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 a specific verb (get) and resource (find), then defines what a find is: 'One result of a long or packaging run with every field'. It names the sibling tools that produce the id (get_run, list_kept_finds), so an agent can place it in the workflow without opening a schema.

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

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

Explains where find_id originates ('from a run's finds (get_run) or from list_kept_finds'), which tells the agent when this tool becomes callable. It stops short of explicitly contrasting with list_finds or other retrieval siblings, so it is clear context but not full when/when-not routing.

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

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

With no annotations provided, the description carries the full burden. It discloses edge cases: null player_url for unusable ids or photo posts before 2026-09-26, and that runs deliver single videos only. It also states the tool is 'Free', which is a cost-related behavioral trait. This is good disclosure 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 a single, dense sentence that packs in the resource, field list, edge cases, parameter source, and cost. Every clause earns its place, and the most important information (what the tool returns) is front-loaded.

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

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

The tool has an output schema, so return values are covered elsewhere. The description covers the key behavioral edge cases and parameter source. It doesn't mention pagination or rate limits, but for a single-resource fetch with an output schema, the description is largely complete. The only gap is api_key semantics, which is minor.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that hook_id comes from get_run, which adds meaning to the required parameter. However, it doesn't describe api_key at all, and the description doesn't fully explain the format or constraints of hook_id beyond its source. Baseline 3 is appropriate since the description adds some value but leaves api_key undocumented.

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: 'One hook with every field' – it retrieves a single hook with all its fields. It distinguishes itself from siblings like get_run and find_hooks by focusing on the hook entity and its fields. However, it doesn't explicitly name a sibling alternative, so it's clear but not fully differentiated.

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 says hook_id comes from get_run, which tells the agent where to obtain the required parameter. It also notes that runs deliver single videos only, which implies a usage constraint. It doesn't explicitly state when not to use this tool or name alternatives, but the context is reasonably 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses cost ('Free'), an ownership/authorization scoping rule (404 remix_not_found 'for one that is not yours'), and immutability of the stored answer. It leaves out pagination/rate-limit behavior, but the key non-obvious traits are present.

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

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

Three short sentences, front-loaded with what the tool returns, and each carries a distinct fact (source, cost, error/ownership, underlying endpoint). The 'as its answer held it' clause is the only mildly wasteful/awkward phrase.

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 described; the description covers cost, ownership, and error behavior for a simple single-resource getter. The main gap is the undocumented api_key parameter, which is a minor omission for what is likely a standard auth field.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does not. remix_id is only indirectly implied via the 'GET /v1/remixes/{remix_id}' reference, and the api_key parameter is never explained at all.

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 (fetch) and resource (one remix), and names where remixes come from (remix_hook, remix_find, chat turn), implicitly distinguishing it from list_remixes and the creation siblings. The phrasing 'as its answer held it' is slightly opaque but conveys a point-in-time snapshot.

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

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

It gives provenance context (which tools produce remixes) and an error condition, but never explicitly states when to call this versus siblings like get_hook or get_find, or when a remix is the right artifact to retrieve. Usage is implied rather than directed.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses that reading a run is free (no credits), that since must be an ISO timestamp with a timezone or a 422 invalid_request occurs, and the wait_seconds bounds/polling behavior. It does not cover authentication requirements for api_key or any rate limits, keeping it short of a 5.

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 first sentence and the wait_seconds/since guidance are front-loaded and useful, but the bulk of the text is an exhaustive data dictionary of return fields (hooks, virality fields, feed, scan tiles, patterns). Since an output schema exists, this return-value enumeration is largely redundant and inflates the description into a dense wall of text.

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 the presence of an output schema, the description supplies more than enough context to invoke the tool correctly: purpose, cost, polling strategy, since semantics and error behavior. The one gap is the undocumented api_key parameter, and much of the return-value detail is surplus rather than missing.

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

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

Schema coverage is only 25% (wait_seconds alone is documented in the schema), so the description must compensate. It richly explains since (pass the last progress.updated_at for change/completion, timezone requirement, 422 on failure) and the wait_seconds usage pattern, but says nothing about run_id or api_key semantics. It adds real value for two of four parameters while leaving the credential and identifier params unaddressed.

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

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

The opening line states the resource and scope precisely: a single research run with its status, progress, charge and every hook. Combined with the required run_id, an agent can tell this retrieves one run rather than listing runs. It does not explicitly contrast itself with siblings like list_runs or get_hook, so differentiation is implied rather than stated.

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?

Strong operational guidance: it prescribes a polling pattern (wait_seconds=50, call again while status is queued/running, ~3-4 calls for a fresh run) and explains when to pass since. What is missing is any explicit routing to sibling tools (e.g., list_runs vs get_run, or get_hook) for related needs.

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 does well: it discloses that the last verdict wins, that the verdict applies retroactively to every find of the same video on that tab, cross-run persistence, the response shape, that it is free, and the 404 find_not_found error. Auth/permission behavior tied to api_key is not addressed, but overall behavioral disclosure is strong.

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 action and default are front-loaded, which is good. But the sentence 'The verdict is the video's on that tab: every find of the same video you have there carries it...' is convoluted and repetitive, and the response/endpoint/error tail reads as an unstructured dump rather than efficient prose.

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 explaining return values is optional (the description does it anyway), and the error case plus the cross-run persistence model are covered. It is nearly complete for a 3-parameter mutation, with the only real gap being auth/permission prerequisites for api_key.

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

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

Schema description coverage is 0% and the description compensates meaningfully for verdict by enumerating the two accepted values ('keep' default, 'reject'), which the schema lacks even as an enum. find_id is implicitly clear, but api_key is documented nowhere, leaving one of three parameters unexplained.

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 gives a specific verb+resource ('Keep or reject a find') and even defines what a find is ('a long-form hook or a package'), disambiguating it from some siblings. It stops short of explicitly differentiating from close siblings like keep_hook or clear_find_decision, so it is clear but not fully routed.

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

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

It explains the verdict semantics (default 'keep', 'last verdict wins') and mentions list_kept_finds as the downstream consumer, which implies when to use it. However, it never states when to use this versus clear_find_decision or keep_hook, leaving the alternative-selection decision to inference.

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 does well: it discloses the default verdict ('keep'), the overwrite semantics ('the last verdict wins'), the note length cap (280 chars), the enumerated reason values, and that the operation is 'Free'. It omits auth/permission behavior despite an api_key parameter existing, which keeps it out of the top band.

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 action and default are front-loaded, and each sentence adds distinct information (default verdict, overwrite rule, reason values, note limit, retrieval, cost) with no filler. It is dense but not bloated.

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 explained, and the description still covers the behavioral essentials an agent needs: default, overwrite behavior, reason vocabulary, note constraints, cost, and where keeps are later found. Missing only auth/permission context for the api_key parameter.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the substantive parameters: it defines verdict values and default, enumerates all reason options, and caps note at 280 characters. hook_id is self-evident from the name and api_key is left unexplained, but the semantically important parameters are well covered.

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+resource combination ('Keep or reject a hook'), so an agent immediately knows this sets a keep/reject verdict on a hook. It references the retrieval counterpart list_keeps, giving some sibling orientation, but does not explicitly distinguish itself from related tools like keep_find or clear_decision.

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 rather than stated: the agent can infer this is the tool to record a verdict on a hook, and the note that keeps surface via list_keeps clarifies the downstream effect. However, there is no explicit when-to-use versus when-not guidance and no named alternative for competing actions.

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 of behavioral disclosure. It reveals sorting behavior (newest first), the specific fields returned, the fact that the code itself is never included, and the 'Free' aspect. It does not mention authentication details beyond 'Owner only', nor does it describe pagination or error behavior, but the provided details are meaningful and beyond what a schema would indicate.

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 highly concise, using a terse but information-dense style. It front-loads the key facts: owner restriction, the resource, sorting, and the returned fields. Every sentence adds value without redundancy, and it is appropriately sized for the tool's simplicity.

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 is simple with one optional parameter and an output schema present. The description covers the core behavioral aspects: listing, sorting, field set, and exclusion of the code. It does not mention pagination or any rate limits, but for a listing tool with an output schema, the description is largely complete. The lack of api_key explanation is a minor gap.

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

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

There is one parameter, api_key, with 0% schema description coverage. The description does not mention api_key at all, leaving its purpose unexplained. While it is optional with a default null, the description does not compensate for the lack of schema documentation. This is a significant gap for the only 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 clearly states the tool lists all access codes for the owner, sorted newest first, and enumerates the exact fields returned (code_id, code_prefix, email, note, etc.). It also explicitly says it never returns the actual code, distinguishing it from operations like create_access_code or revoke_access_code. This is a specific verb + resource with clear scope.

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

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

The description includes a usage restriction ('Owner only') which is a clear condition for when to use the tool. It also states 'every access code' implying a comprehensive listing, which contrasts with list_access_requests. However, it does not explicitly name an alternative tool or state when not to use it, so it misses some explicit routing guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it indicates a read-like list operation, defines ordering, declares the returned fields, states that codes are never included, discloses an auth failure mode, and notes the tool is free. This is strong added context beyond any 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 about 60 words and every sentence earns its place: scope/order/filter, output fields, exclusion of codes, and auth/pricing. Information is front-loaded and there is no filler or repetition.

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

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

Given the output schema exists and the description already enumerates returned fields, the definition covers ordering, filtering, output contents, auth requirements, and cost. The only notable gap is the undocumented api_key parameter, which an agent may need clarified to call 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 0%, so the description must compensate. It clearly defines the status parameter's allowed values (pending, approved, rejected) and optionality, which adds real meaning beyond the bare schema. However, the api_key parameter is never mentioned in the description, leaving its format, purpose, and relation to the admin requirement implicit.

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

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

The description names a specific verb and resource: listing every access request, with ordering (newest first) and an optional status filter. This clearly distinguishes it from sibling tools like list_access_codes or request_access, so an agent can select it without ambiguity.

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

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

The description gives explicit preconditions: owner only, admin scope required, and an admin account, including the resulting 403 error if unmet. It does not explicitly name alternative tools for related actions (e.g., approve_access_request), but the use context is clear enough for correct 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, the description carries the full burden and does so well: it discloses sort order, the default page size, the 1-100 bound, cursor mechanics for subsequent pages, endpoint equivalence (GET /v1/conversations), and that language/country reflect saved search picker settings. It omits auth requirements despite an api_key parameter, which is the main residual gap.

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

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

Dense and front-loaded, leading with the resource, ordering and limits, with zero filler sentences. The telegraphic style is efficient though somewhat run-on, which keeps it just shy of a 5.

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 needn't be restated, yet the description still characterizes the field list and response envelope, and covers pagination, cost, and the natural next tool. Only the auth/credential expectation around api_key is left implicit.

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

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

Schema coverage is 33%, so the description must compensate and largely does: it supplies the default (30), the range, and crucially the cursor contract ('pass next_cursor back as cursor for more'), which the bare schema does not explain. The api_key parameter remains semantically unaddressed.

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 a specific verb and resource ('Your chat conversations'), the ordering ('most recently active first'), and the field set returned, then routes to the sibling 'get_conversation' as the next step. An agent can distinguish this list tool from get_conversation without opening either schema.

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

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

Gives explicit pagination guidance ('pass next_cursor back as cursor for more') and names the follow-up tool ('Next step: get_conversation'), plus a cost signal ('Free.'). No explicit when-not-to-use case, but the context for calling it is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return object ({finds, count, total, next_cursor}), the pagination protocol ('pass next_cursor as cursor'), cost ('Free'), and error behavior (422 for invalid kind/sort/tier/min_score/device/q). It omits auth/permission requirements (the api_key param goes unexplained) and any rate-limit info, which keeps it from a 5.

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?

It is front-loaded with the core purpose, but the prose runs long with dense parentheticals, and it re-enumerates the return object ('Returns {finds, count, total, next_cursor}') that the output schema already defines. Most clauses earn their place, but the wall-of-text structure and schema repetition cost it.

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 9-parameter, zero-required list tool with an output schema present, the description is nearly sufficient: it covers filtering semantics, ranking, pagination continuation, cost and the 422 error surface. The only notable omission is authentication/usage of api_key, which no structured field documents.

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 78%, so the baseline is 3, but the description adds real meaning: q is capped at 120 characters and searches title, channel, spoken hook and thumbnail content, with concrete examples ('red arrow', 'before and after'), and outlier_score is explained as a fixed 0–100 scale that lets entries from different runs rank together. Cursor and api_key remain unelaborated.

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 a specific verb and resource ('The index: every video your long and packaging runs found, across all runs'), and clarifies scope (all runs, one entry per video, newest read with its keep/reject). It is very clear what the tool returns, but it never names a sibling such as list_kept_finds or list_keeps to disambiguate, so it stops short of a 5.

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

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

Gives an explicit use case: 'Use it to search what you already paid for before starting a new run,' which implicitly points away from the run-starting tools. There are no explicit when-not-to-use conditions or named alternatives, so guidance is clear but incomplete.

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 behavioral burden and does so thoroughly. It discloses the output shape, pagination mechanics, default and allowed limits, ordering, cost ('Free'), and error conditions ('422 for a bad run_id or cursor'). This is exceptional 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 description is dense but every sentence contributes: what is listed, how it is ordered, scoping, pagination, output shape, reference endpoint, cost, and errors. It is front-loaded with the core purpose and contains no filler.

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

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

For a list-with-pagination tool, the description covers everything needed to invoke it correctly: limit range, cursor continuation, run_id filtering, response shape, error handling, and cost. The output schema exists, but the description adds the operational context an agent needs.

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 low (25%), so the description must compensate. It adds meaningful semantics for run_id and cursor, and the limit behavior is also referenced. The api_key parameter is not described, but it is self-explanatory and nullable, so the gap is minor.

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

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

The description names the specific resource ('hooks you kept with keep_hook'), the operation (list), the ordering ('newest decision first'), and the scoping options ('across all runs or within one run_id'). It clearly distinguishes itself from sibling tools like find_hooks or get_hook by focusing specifically on kept hooks.

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

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

The description makes the usage context clear: list kept hooks either globally or scoped to a run_id, with pagination via cursor. It does not explicitly name alternatives or state when not to use this tool, but the scoping and pagination details give strong practical 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses sort order (newest decision first), granularity (one entry per video per tab), pagination, that it is free, and specific error behavior (422 for bad kind/run_id/cursor). It stops short of stating auth requirements or rate limits.

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

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

Information is front-loaded with the resource and origin first, then scope, paging, return shape, cost and errors. It is dense and slightly run-on ('one entry a video on each tab across all runs'), but no sentence is wasted.

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

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

For a paginated list tool with an output schema, the description covers filtering, ordering, paging, return shape and errors, which is nearly everything an agent needs. Only auth context is absent, and the return values are already backed by the output schema.

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

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

Schema coverage is only 40%, and the description compensates by clarifying limit bounds and default, the run_id scoping meaning, the kind choice, and the cursor via the next_cursor return. It adds real meaning beyond the sparse schema, though api_key is left unexplained.

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 a specific resource ('the videos you kept with keep_find') and explicitly ties it to the sibling action that produced the data, plus a scope note about long-form hooks and packages. It does not explicitly distinguish itself from the sibling list_keeps, so it falls short of a 5, but an agent can tell what it lists.

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 describes the two retrieval modes (all runs vs. one run_id) and mentions the kind filter, which implies when to use it. However, it never names an alternative such as list_keeps or list_finds and gives no when-not guidance, leaving routing between the sibling list tools to inference.

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 shoulders the full burden. It reveals the admin requirement, that secret keys are never shown again, that 'current' and 'scopes' are relative to the calling key, and the special 'original' key ID. It does not discuss error cases or rate limits, but coverage is strong for a read-only list operation.

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

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

The description is dense and front-loaded: the purpose statement comes first, followed by compact field enumeration and key constraints. The trailing 'Same shape as GET /v1/keys' and 'Free' are useful but slightly redundant given the output schema, costing a point.

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 list operation, the description covers the essential semantics: admin requirement, key ID schema, per-key access fields, and the calling-key relationship. The only notable omission is explicit guidance on the api_key parameter itself, but the rich output schema and output-shape mention reduce the gap.

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

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

The sole api_key parameter has no schema description, and the description never names it directly. It does indirectly clarify its role via 'current (true for the key making this call)' and 'scopes: the calling key's,' which tells the caller that the supplied key determines the response. That partial compensation warrants a middle score rather than lower.

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 'Your API keys and what each may do,' which clearly identifies the resource and the listing intent, and enumerates output fields. It does not explicitly use the verb 'list' or call out sibling alternatives, so it stops short of a 5.

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

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

It gives useful context ('Needs admin', 'Free', 'Same shape as GET /v1/keys') and the output shape implies this is the read-only view of keys. However, it never states when to prefer this over create_key/revoke_key or other siblings, leaving the comparison implicit.

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 does well: it discloses ordering ('newest first'), the fields returned ('remix_id and created_at'), that it is 'Free', and error semantics ('404 hook_not_found or find_not_found for one that is not yours'). Pagination/limits are not mentioned, which keeps it from a 5.

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 and dense with no filler sentences. The clause 'each as its answer held it' is cryptic and slightly reduces clarity, but overall it earns its space.

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

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

An output schema exists so return-shape detail is not strictly required, yet the description still summarizes it and covers errors, cost, and ordering. For a filtered list tool this is nearly complete; only pagination/volume behavior is missing.

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

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

Schema coverage is 67%, just under the high baseline. The description reinforces the mutual-exclusivity of hook_id/find_id and that they must be 'yours', but the api_key parameter is undocumented in both schema and description, and no ID format or syntax is added.

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 a specific verb and resource ('list remixes') with explicit scope ('you paid for from one hook or one find'). This distinguishes it from get_remix (single item) and the find/hook listing siblings without opening any schema.

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

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

The either/or selection rule (supply hook_id OR find_id) is stated, which is genuine usage guidance. However, no alternative tool is named and there is no when-not guidance (e.g., versus get_remix or list_finds), so it stays at implied usage.

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 does so well: it discloses ordering (newest first), pagination contract (next_cursor passed back as cursor, null on last page), cost ('Free'), and error behavior (422 invalid_cursor, 422 for an invalid kind). This is unusually rich behavioral context for a list operation.

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

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

Front-loaded with the core behavior and efficiently packs kind mapping, return shape, pagination and errors. It is dense but largely earns its length; the 'Same shape as GET /v1/runs' line is the only clause of marginal value to an agent.

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 paginated list tool with four params and an output schema, the description covers ordering, filtering, pagination, cost and failure modes, so an agent has everything needed to call it correctly.

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

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

At 50% schema coverage the description compensates by explaining kind values, the 1-100 limit range with default 20, and cursor semantics. The api_key parameter remains undocumented in both schema and description, keeping it short of a 5.

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 a specific verb+resource ('Your research runs, newest first'), scoping detail ('without their results') and enumerates the three run kinds. An agent can distinguish this listing tool from get_run/export_run without opening a schema.

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

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

Explicitly guides filtering ('pass kind to list only one') and names the next tools ('open one with get_run, or download it with export_run'). It does not, however, contrast itself against the sibling admin_list_runs, so the routing against other list tools is left implicit.

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

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

With no annotations provided, the description carries the full burden. It discloses the permission requirement (owner only), a key side-effect absence (nothing is emailed), the exact error for already-decided requests (409 request_already_decided), and cost ('Free'). It does not describe the success response or that the request becomes rejected, but those are inferable and not critical gaps.

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, each adding distinct value: permission, action, side-effect note, error condition, and cost. Information is front-loaded and there is 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?

The tool is simple (2 optional params, no enums, output schema exists), and the description covers purpose, permission, and error behavior. However, it leaves api_key entirely unexplained and gives no hint about where to find the request_id (e.g., via list_access_requests). These gaps make the tool slightly under-specified for an agent to call it correctly on first try.

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

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

Schema description coverage is 0%, so the description must compensate for explaining the parameters, but it does not mention api_key or request_id at all. The names are self-explanatory to some degree, but no guidance is given on how to obtain request_id or whether api_key is required for authentication. This is a significant gap for a two-parameter tool.

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

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

The description states a specific verb-action pair ('reject a pending access request') and clarifies the resource (access request) and scope (owner only). It is clearly distinct from sibling approve_access_request and other 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 gives useful context: only for pending requests, only by the owner, and that already-decided requests produce a 409. It does not explicitly name the approve alternative or state when not to use it, but the pending-request condition effectively rules out non-pending cases.

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 does so thoroughly: 1 credit charged before the model runs and refunded on 503 or 422, 402/404/429 error conditions, hourly rate limit, required research permission, idempotency behavior, and the fact that remixes are never added to a run, keep or export. It even discloses that outputs are drop-filtered if they copy the real find's words.

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 purpose but then unspools into long run-on sentences with inconsistent backtick formatting and no structure. A substantial portion enumerates the shape of `written` for each mode, which the output schema already covers, so not 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?

For a 7-parameter, credit-consuming, permission-gated generation tool, the description covers cost, refunds, errors, permissions, rate limits, output label semantics and idempotency. With an output schema present, it correctly does not need to explain return values, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is high at 86%, so the baseline is 3, but the description adds real meaning beyond the schema: in intro mode niche and n are unused, numbers not written in video_brief become {number} placeholders, and a copy or word-budget overrun yields 422 remix_not_possible. These are behavioral rules about how inputs are interpreted, not restatements of 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 opening states a specific verb and outcome: write up to n new openings/packages/intros for your niche that keep one real find's structure. That is distinguishable from short-form siblings like remix_hook and from find_long_hooks/find_packaging, though the comparison is left implicit. The cryptic phrasing 'Make it mine' adds noise before the actual purpose lands.

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 routes between the two modes clearly: 'openings' (default) writes openings or packages for a niche, while mode 'intro' writes your own timed intro and does not use niche or n. It also states the precondition that intro only works on a long find (a packaging find is 422). It never names sibling tools to use instead, so the boundary with remix_hook or find_long_hooks must be inferred.

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 does so richly: 1 credit charged before the model is asked and refunded on 503/422, 402 at zero balance, 429 hourly rate limit, research permission requirement, and the crucial disclosure that outputs are written lines never to be presented as real hooks or added to decks/keeps/exports. 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 main action is front-loaded and every sentence carries information (costs, refunds, error codes, labeling rules, read-back tools). It is dense and long, and the return-shape recitation overlaps with the output schema, but there is little pure padding.

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 credit-charging generative mutation with no annotations, the description covers permissions, charging, refund semantics, error codes, rate limits, labeling obligations, and read-back tools. An output schema exists, yet the description still names remix_id for list_remixes/get_remix, leaving no gap an agent needs to call this 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 83%, so the schema already documents n, mode, niche, hook_id, and idempotency_key. The description still adds meaning by tying hook_id to its provenance tools and its 404 failure mode, and by reinforcing the n default and the mode refusal. It stops short of adding new syntax beyond the schema, so a 4 rather than 5.

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 a specific verb and resource: write up to n new opening lines that keep a real hook's structure with the subject swapped. It explicitly separates itself from remix_find by explaining that 'intro' mode belongs to a long-form find and is refused here. An agent can distinguish this from remix_find and get_hook without opening a schema.

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

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

Names the sources for hook_id (get_run, get_hook, list_keeps), states that mode should be left out, and routes the 'intro' case to remix_find. It also gives explicit when-not conditions via error codes (422 for intro, 404 for unknown hook). Nothing about selection is left to inference.

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 responsibility and covers a lot: owner approval flow, immediate emailing, one-time use, no key needed, rate limit of 5 per address per hour, and the pending/emailed statuses. This is unusually complete 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 compact and front-loaded with the tool's purpose, then adds only high-value operational details. No redundant or filler content.

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

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

For a tool with only two simple parameters, the description covers input semantics, expected workflow, return statuses, authentication, and rate limiting. Nothing an agent needs to call it correctly is missing, and the output schema covers the return structure.

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

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

Schema coverage is 0%, but the description compensates fully: email is the destination for the code, and note is optional, identifies the requester, and is capped at 500 characters. Both parameters are explained beyond the bare schema.

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

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

The description opens with a specific verb and resource: 'Ask for the beta access code a new account needs' and ties it to create_account's access_code, so an agent can tell this is the request path rather than create/approve/reject/list. It clearly differentiates the tool from siblings like approve_access_request and create_access_code.

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

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

It gives clear context: use this when a new account needs a beta access code and the owner must approve it before the code is emailed. It does not explicitly name alternatives or when not to use it, but the workflow is unambiguous enough to select this tool over 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, the description carries the full burden and does it well: it discloses ownership restriction, the future-denial side effect, that existing accounts remain functional, the 404 error for unknown ids, and cost. This is unusually complete behavioral context.

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

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

Three compact sentences, each earning its place: authorization, side effects, error behavior, and cost. The most important contextual constraint ('Owner only') is front-loaded, and there is no filler.

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

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

For a two-parameter revoke operation with an output schema, the description covers the essentials an agent needs: permission, expected input source, persistence semantics, and an error case. Nothing else is required for safe 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?

Despite 0% schema description coverage, the description gives a valuable hint that code_id comes from list_access_codes and links it to the revoke behavior. api_key is not described, but its name/title and this tool's 'Owner only' context make its role reasonably clear; this is a minor gap rather than a severe one.

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, 'revoke an access code', and gives the source of the identifier ('code_id from list_access_codes'), which clearly distinguishes it from sibling tools like revoke_key. It also states the intended effect, so an agent can identify the tool by behavior, not just name.

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?

'Owner only' gives a clear prerequisite, and 'code_id from list_access_codes' tells the agent where to obtain a valid input. It does not explicitly say when not to use it or name revoke_key as the alternative for keys, but the access-code scope is clear enough for most selection cases.

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

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

With no annotations provided, the description carries the full burden. It discloses all critical behaviors: self-revocation works immediately, revoking others requires admin, the last active key cannot be revoked, and the 'others' special value revokes all but the calling key. It also states the result fields (revoked_count and retained key) and cost implications ('Free'). This is exceptionally transparent.

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

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

The description is dense but every sentence contributes essential information. The main use case is front-loaded, then constraints and edge cases follow logically. The special 'others' case is given its own paragraph, improving readability. No filler or redundancy.

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

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

Given the tool's complexity (special values, admin requirements, error conditions, output details), the description covers all aspects: the key_id special cases, permission model, 409 failure mode, result format, and cost. It even explains the behavior of the 'others' case in detail. An agent armed with this description can invoke the tool correctly in every scenario.

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

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

Schema coverage is 0%, so the description must explain parameters. Key_id is thoroughly explained, including special values 'original' and 'others', and the behavior they trigger. The api_key parameter is implicitly covered by the phrase 'the one you are calling with', clarifying its role in the revocation. The description adds meaning far beyond the raw schema fields.

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

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

The description begins with 'Revoke one of your API keys at once' – a specific verb, resource, and scope. It also distinguishes itself from siblings by mentioning 'list_keys' and 'create_key' directly, making it clear which tool to use for key management actions.

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 the tool (to revoke keys), when to use alternatives (create another key before revoking the last), and when to use the special 'others' value for leaked keys. It also outlines conditional requirements like admin privileges and the 409 restriction, leaving no ambiguity about invocation conditions.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: no API key required, results cached 10 minutes, free, public-only content, and a hard one-per-creator + view-sorted ordering. It omits any rate-limit or freshness/refresh behavior beyond the cache window, and does not explicitly label the operation read-only, keeping it below a 5.

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 content is dense and mostly front-loaded, but the telegraphic fragment style with multiple parentheticals is harder to parse than it needs to be, and 'No key needed' is stated twice while 'Free.' is redundant filler. It is not bloated, but it could be tightened into cleaner sentences.

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, zero-required-parameter tool with an output schema, the description covers the essential behavioral facts an agent needs (no auth, public-only, caching, ordering, cardinality). Return-field detail is covered by the output schema, so nothing critical is missing.

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

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

Schema coverage is 100% and the single 'n' parameter is already documented as clamped to 1-24 with default 12. The description only restates n via the REST example ('?n=12'), adding no new meaning over the schema, 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 description states the resource precisely: real delivered hooks for a wait screen, restricted to talking heads, sorted by most-viewed, one per creator. It implicitly distinguishes itself from filter-style siblings like find_hooks by saying it never takes a topic, account or run. A clearer leading verb (e.g. 'Lists') would make the purpose unmistakable, but the scope is 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?

'For a wait screen' gives a concrete use context, and 'only what is already public' implies the tool is for display of public content rather than searching. However, no sibling is named as an alternative and no explicit when-not guidance is given; the agent must infer that find_hooks/get_hook are the search counterparts.

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 behavioral burden. It usefully explains that reserved_now credits are held by in-flight runs and partially refunded, that recent is limited to the 20 newest runs, and that last_30_days is per-UTC-day. 'Free' indicates the cost profile, and the API-shape note adds context. It stops short of explicitly stating read-only or no side effects, but the informational framing strongly implies a safe query.

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 followed by two short fragments. It front-loads the core purpose and efficiently packs field semantics without fluff. The structure is slightly run-on, but every element 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?

The tool has zero required parameters, an output schema exists, and the description already enumerates the returned fields, their meanings, and the cost profile. An agent has everything necessary to invoke this tool correctly. The only missing piece is sibling routing, which is covered under usage guidelines.

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

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

Schema description coverage is 0%, and the description does not mention api_key at all. The parameter is optional with a default of null, so the gap is less severe, but an agent still cannot tell why or when to provide an api_key (e.g., overriding the default key). The description fails to compensate for the coverage gap.

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 states the tool's purpose: reporting credits and spending. It enumerates the exact fields returned (credits, spent_total, reserved_now, runs_total, last_30_days, recent), making the resource and output clear. It does not explicitly differentiate from the sibling 'balance', but the detailed field list gives enough specificity.

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

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

No guidance is given about when to use this tool versus 'balance' or 'list_runs'. The description mentions the data returned, but does not state contexts, exclusions, or alternatives. 'Same shape as GET /v1/usage. Free.' is technical detail, not usage direction.

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