Hook Detector

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 burden. It discloses costs (free turn but model call, rate limits), error codes (429, 503, 402, 403), permissions (needs write permission), and the next step (call get_run). It also describes response suggestions. This is comprehensive and exceeds typical 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 dense with information but well-structured, front-loading the core purpose and actions. While it is somewhat long, every sentence adds value—covering usage, errors, and next steps. It is not verbose or redundant, but could be slightly tighter by grouping related details.

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

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

Given the tool's complexity (three actions, multiple error types, permissions, rate limits, next steps), the description is remarkably complete. It covers what the tool does, when to use it, parameter semantics for the main inputs, behavioral details, and even hints at the response structure. The only missing piece is api_key, which is likely standard and not critical.

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 message length (1-4000 chars) and conversation_id usage ('Pass conversation_id from an earlier turn to keep the context; leave it out to start a conversation'), but does not mention api_key at all. This covers two of three parameters well, but the omission of api_key is a minor 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 it is a conversational turn with three specific actions (clarify, answer, research), and explicitly differentiates from find_hooks, saying 'For direct research without the question step, call find_hooks instead.' This gives a specific verb+resource and distinguishes it from siblings.

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

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

The description explains when to use each action (clarify, answer, research) and provides explicit alternatives, such as using find_hooks for direct research. It also states the next step to call get_run after a research action, giving clear guidance on 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 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 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?

No annotations are provided, so the description carries full burden. It discloses cost reservation (up to 200 credits), refunds, failed runs costing nothing, idempotency behavior, reuse semantics, timing expectations, permission requirements (research permission), and specific error codes (403 insufficient_scope, key_credit_limit_reached). It also notes unmeasured behavior for mixed language values, showing honesty about limitations.

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 tightly packed; every sentence adds necessary detail. It is structured into clear sections (What it does, Arguments, language/country, Cost, Timing and next step), and front-loads the core purpose and key parameters. 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?

Given the tool's complexity (9 parameters, output schema present), the description is remarkably complete. It covers cost, refunds, timing, progress monitoring, error scenarios, region handling, and even points to llms.txt for exact numbers. It also explains what the output contains (verbatim opening line, quotable line, etc.), making it self-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 89%, but the description adds substantial meaning beyond parameter descriptions: it explains idempotency_key's 24-hour dedup behavior, reuse's cost-saving mechanism, wait_seconds' dual behavior (returns run_id vs run object), and the language/country interplay (country alone does not restrict language, regional varieties). These clarifications are not in the schema.

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

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

The description opens with a specific verb and resource: 'Start hook research on a topic across TikTok and Instagram.' It clearly distinguishes this tool as the entry point for research, contrasted with siblings like get_run and get_hook which handle retrieval. The scope (both platforms, ranked hooks) is explicit.

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 guidance on when to use reuse, idempotency_key, and wait_seconds, including a concrete next-step instruction: 'Call get_run with wait_seconds=50 repeatedly until status is done or failed.' It also covers language/country usage and region examples, leaving no ambiguity about alternatives or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden and does well by disclosing that the tool is 'Free,' the exact error codes (404, 422), and that the response matches a known REST endpoint. It does not discuss authentication or rate limits, but the provided information meaningfully exceeds 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?

Three tightly packed sentences: return content, REST equivalence, and error/cost. No redundant words, and the most useful information is front-loaded. Every sentence earns its place.

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

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

Given the output schema, the return shape is covered, but the description still lacks guidance on how to obtain conversation_id (e.g., via list_conversations) and what happens with an invalid or missing api_key. With no annotations and zero schema descriptions, a bit more context about prerequisites and authentication would be expected.

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 explain parameters. It implicitly covers conversation_id through the REST path and UUID error, but api_key is never mentioned or explained—leaving the agent to guess its purpose or whether it is 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 clearly states it returns one chat conversation with every message in order and all runs/hooks, and even names the exact REST endpoint. This singular framing distinguishes it from siblings like list_conversations, making the tool's purpose unambiguous.

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

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

No direct guidance is given about when to use this tool versus list_conversations or get_run, nor does it mention that a conversation_id must first be obtained via list_conversations. The only implied usage is from the tool name and 'One chat conversation,' which is insufficient.

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 of behavioral disclosure. It thoroughly explains the polling behavior, the significance of since, the outcome field for incomplete runs, the transcript_kind values, conversation_id, and that it is free. It also mentions a specific error case (422 for invalid since timestamp). This is robust, though it doesn't cover potential rate limits or other side effects.

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

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

The description is long but every sentence provides actionable detail. It is front-loaded with the definition, then flows into usage, edge cases, and output semantics. No fluff; the length is justified by the tool's complexity. It is well-paragraphed and readable.

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

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

Given the tool's complexity, the description covers polling, error handling, output nuances, and free cost. An output schema exists, so return values need not be enumerated. It lacks some prerequisites (e.g., how to obtain run_id), but that is often implied. Overall, it is sufficiently complete for an agent to call 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 low (25%), so the description compensates significantly. It explains wait_seconds (0-50, polling strategy, repeated calls), since (ISO timestamp with timezone, use with progress.updated_at for change/completion), and implicitly run_id (the run to retrieve). It does not detail api_key, but that is a standard parameter. The description adds substantial context beyond the schema.

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

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

The description clearly states it retrieves a research run's status, progress, charge, and hooks. It is specific and uses a clear verb-resource structure. However, it does not explicitly differentiate from sibling tools like list_runs or get_hook, so it lacks the additional distinction that would merit 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?

The description provides detailed instructions on how to use wait_seconds and since for polling, but it does not indicate when to use get_run versus alternative tools (e.g., list_runs for listing runs, get_hook for specific hooks, export_run for exports). No guidance on tool selection is given.

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 must carry behavioral disclosure. It notes that 'the last verdict wins' (overwrite behavior) and that it is 'Free,' which are useful. However, it does not disclose side effects on existing hooks, error behavior, or authentication requirements. It provides some behavioral context but not a comprehensive picture.

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

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

The description is two sentences long and packs essential information efficiently. It front-loads the primary purpose ('Keep or reject a hook') and then adds detail. While it is slightly dense, there is no waste, and the structure is logical. It could be more modular but is appropriately concise.

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

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

Given the tool has three parameters and an output schema, the description is not fully complete. It explains the core action and the verdict behavior, and references list_keeps for context. However, it omits any description of what a hook is, how to handle the api_key, and potential errors or side effects. Since annotations are absent, more context is needed for a complete picture.

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

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

The schema description coverage is 0%, so the description must compensate. It explains the verdict parameter (including default) but leaves hook_id and api_key entirely unexplained. The hook_id is only identified by its name in the schema, and api_key is not addressed at all. Since only one of three parameters is clarified, the compensation is insufficient.

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 clear verb and resource: 'Keep or reject a hook.' It also specifies the verdict parameter and its default. However, it does not explicitly differentiate from siblings like get_hook or find_hooks, though the relationship to list_keeps is hinted. This is clear but not fully distinct.

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

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

The description mentions that kept hooks come back from list_keeps, which implies a usage context but does not explicitly say when to use this tool versus alternatives. It lacks guidance on when not to use it or which sibling to choose instead. The relationship to list_keeps is a hint but not an explicit routing instruction.

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 behavioral burden. It discloses ordering, default page size, response shape, cursor behavior, endpoint equivalence, and that it is free. It does not mention auth/error behavior, but for a read-only listing tool this is a strong 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 key behavior, then pagination, response shape, and follow-up. A few extras like 'Free' and 'Same shape as GET /v1/conversations' are minor but relevant, so nothing feels 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?

Output schema exists, so return value details are already structurally documented. The description covers the main operational concerns: sort order, limit, cursor pagination, and next step. The missing api_key guidance is the main 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 coverage is only 33%, but the description adds cursor semantics ('pass next_cursor back as cursor') and restates the limit range. The api_key parameter remains entirely undocumented in both the schema description and prose, which is a notable 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 identifies the resource (chat conversations) and the operation (listing them), and adds pagination and field details. It also distinguishes this from the sibling get_conversation by naming it as the next step.

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

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

It provides clear context: use this for paginated listing of conversations, with cursor-based traversal for more results, and directs the agent to get_conversation next. It does not list explicit exclusions, but the sibling relationship is sufficiently 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 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 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 provided, the description carries the full behavioral burden and does so well. It discloses ordering, omission of hooks, pagination semantics, the exact error case (422 invalid_cursor), cost ('Free'), and API shape equivalence, giving the agent a strong model of what the tool does before invocation.

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

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

The description is dense but not bloated: every sentence contributes operational detail—scope, ordering, pagination, errors, follow-up actions, and cost. Information is front-loaded, starting with what the tool returns and how it is ordered.

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 present, this description is complete: it explains the exact response envelope, pagination flow, error behavior, and next steps. The only minor omission is auth details around api_key, but this does not meaningfully hinder 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 only 33%, but the description compensates for the two most behaviorally important parameters: it explains limit bounds and default, and it gives cursor exact semantics (pass back next_cursor, null on last page). The api_key parameter remains unexplained, though its auth purpose is largely inferable from the sibling tool family.

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 ('your research runs'), the ordering ('newest first'), and a key scoping detail ('without their hooks'), which differentiates it from related tools such as get_run, export_run, and find_hooks. The purpose is immediately understandable without needing to open the 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 description gives concrete operational guidance: how to paginate by passing next_cursor back as cursor, and which sibling tools to use next (get_run or export_run). It does not explicitly state when to avoid list_runs in favor of another listing tool, but the pagination and workflow context are clear enough for an agent to select it correctly.

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

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

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 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 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.