PreVibe

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

Annotations already mark idempotentHint true, openWorldHint true, and readOnlyHint false. The description adds meaningful behavior beyond annotations: it is free, only re-checks names still marked 'not checked,' and returns a run unchanged if all names are resolved. This aligns with and enriches the idempotency annotation without contradiction.

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

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

The description is two sentences with no filler. The main action is front-loaded, followed by cost and idempotency conditions. Every clause adds useful information, making it both concise and complete for the tool.

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

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

For a single-parameter tool with no output schema, the description covers purpose, cost, and behavioral edge cases. It could mention the return type or possible external side effects (e.g., live registrar queries), but the idempotency hint and openWorldHint supplement enough context for correct invocation.

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

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

The schema covers the single 'id' parameter fully with 'The brand-name run ID to backfill availability for.' The description reinforces the run context but adds no new parameter-level details such as format or examples. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Fill in domain availability and prices for names in a run that were saved without them.' It explains the context (registrar throttled at generation time), which makes the tool's purpose concrete and distinct from siblings like get_brand_names or check_credits.

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

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

The description implies when to use the tool: after a run has names without availability due to throttling. It also clarifies that only unresolved names are re-checked, so an agent can decide whether calling it will have effect. It does not explicitly name alternatives, but no sibling does the same thing, so the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety and closed-world behavior are covered. The description adds only the trivial clarification that the balance is for the authenticated user; it says nothing about caching/freshness of the balance or whether it is account- vs workspace-scoped.

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?

One short sentence, front-loaded with verb and resource, with zero filler. Nothing could be removed without losing meaning.

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

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

For a zero-parameter read tool whose annotations already carry the safety profile, the description covers what the agent needs. The absence of an output schema is minor, since 'credit balance' implies a numeric return, but freshness or scope nuances are unaddressed.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly signals that no arguments are needed, and the empty schema leaves nothing 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?

States a specific verb (check) and resource (credit balance) with a clear scope (authenticated user). The sibling list is entirely brand-name/research management, so the distinction is obvious in practice, though the description never explicitly names or contrasts with a 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives or related credit-consuming operations. The natural use case (verifying balance before create_research/create_deep_dive) is left entirely 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?

Beyond annotations, the description adds meaningful behavioral context: it costs 1 credit, targets either the founder's idea or a top bet, and returns a table with domain, availability, price, and companion domains. It does not fully describe side effects or persistence, but the annotations already indicate the operation is not read-only.

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

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

The description is concise and front-loaded: core action first, then target semantics, then cost and output. Every sentence carries useful information 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?

For a two-parameter tool with no output schema, the description is complete enough for an agent to invoke correctly. It covers prerequisites, parameter defaults and options, cost, and the structure of the returned table.

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 for parameters is 100%, so the baseline is 3. The description adds value by explaining the default target ('idea'), what bet-1/bet-2/bet-3 mean, and the requirement that research be complete, going beyond 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?

The description clearly states the verb and resource: 'Generate a set of brandable names for a completed research.' It also distinguishes the tool from siblings like listing, deleting, or suggesting more names by emphasizing grounded positioning and domain-availability checking.

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 usage context: requires the parent research to be complete and explains how the target parameter selects what to name. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5, but an agent can infer the correct use case.

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

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

The description goes beyond the all-false annotations by disclosing that the operation costs 1 credit, that it strictly uses existing research rather than new market data, and that parent research must be complete. It also notes that it returns the full analysis, which is valuable given there is no output 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 dense but every sentence earns its place: purpose, source constraint, parameter clarification, prerequisite, cost, and return value. The most important information is front-loaded, and there is no 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 a tool with no output schema and moderate complexity, the description covers the essential operational context: what it produces, what it requires, how it is sourced, what it costs, and how the target parameter behaves. Nothing critical is missing for an agent to decide whether to invoke 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?

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the 'target' semantics and the omit-default behavior, but adds little beyond the schema's own detailed descriptions. A baseline 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Generate an in-depth framework analysis' for a completed research. It enumerates concrete components (jobs-to-be-done, positioning, MVP scope, Kano, pricing, 90-day plan, risks) and clearly distinguishes itself from research creation by requiring the parent research to be complete.

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

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

The description clearly states when to use the tool: only after research is complete, and only seeded from that research without new market data. It does not explicitly name alternatives like retry_deep_dive or create_research, but the precondition 'Requires the parent research to be complete' provides clear contextual 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?

Beyond the annotations, it discloses a concrete side effect: 'Costs 1 credit.' It also reveals that the response is only a compact summary with verdict badge, score, findings, top bets, and ID/URL, and that the full report must be fetched separately. No contradiction with the 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?

Three dense sentences front-load the main purpose, then cover input constraints, cost, output shape, and follow-up retrieval. Every clause carries useful information with no 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 tool with an output schema, this description fully explains input, cost, and the summary-vs-full-report behavior, including the get_research follow-up. It is slightly incomplete only in not differentiating create_research from create_deep_dive within the sibling tool 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 coverage is 100% and the schema already describes the idea parameter as 'anything from a one-liner to full multiline notes.' The description repeats this and adds the 4,000-character limit already present in the schema's maxLength, so it contributes little beyond the schema.

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

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

The description clearly states the action and resource: 'Generate a comprehensive market research report based on a business idea.' It differentiates from get_research by noting that this call returns only a summary, but it does not explicitly distinguish create_research from the sibling create_deep_dive.

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 for when to call: when a business idea needs market research, and it accepts anything from a one-liner to full notes. It also points the agent to get_research for fetching the full report later, but it does not explain when create_deep_dive or retry_research might be the better alternative.

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

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

Annotations already mark this as destructive and non-read-only. The description adds valuable behavioral details: the action cannot be undone, it is free, and it is restricted to runs whose parent research the authenticated user owns. This goes beyond the annotations without contradicting them.

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

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

The description is three short sentences with no filler. The core action is front-loaded, followed by cost, ownership, and irreversibility constraints. Every sentence adds information the agent needs.

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 delete operation with annotations already covering destructiveness and idempotency, the description is largely complete. It covers ownership, irreversibility, and cost. It could mention the response or behavior when the id does not exist or is not owned, but this is not critical for invoking the tool correctly.

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

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

Schema coverage is 100% and the only parameter, id, is already described as 'The brand-name run ID to delete.' The description adds no deeper semantics beyond restating that deletion is by id, so the schema carries the burden.

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: 'Delete a brand-name run by id.' This clearly differentiates it from sibling tools like delete_research and delete_deep_dive, and clarifies that it targets a run rather than the brand names themselves.

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

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

The description provides clear usage context: the action is free, irreversible, and only permitted when the authenticated user owns the parent research. It does not explicitly name alternative tools or state when not to use this tool, but the ownership constraint and resource specificity give sufficient guidance for selecting it.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description adds meaningful behavioral context: the action cannot be undone, and it is restricted to deep dives whose parent research the authenticated user owns. This goes beyond the annotations and helps the agent anticipate side effects and authorization failure. No contradiction found.

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

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

The description is short and front-loaded with the core action. Every sentence carries meaningful information except perhaps the standalone 'Free.', which is an odd addition but not harmful. The structure is efficient and easy to parse.

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

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

For a simple single-parameter delete operation, the description covers the target, the authorization constraint, and irreversibility. It does not explain error behavior or response format, but the output schema is absent and annotations cover idempotence. Overall, it is sufficiently complete 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 schema has 100% description coverage for the single parameter, and the description simply restates that deletion is by ID. The schema already documents the format, requiredness, and meaning of 'id', so the description adds minimal additional semantic value. Baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Delete'), a specific resource ('deep dive'), and the selection mechanism ('by ID'). It also adds an ownership qualifier that distinguishes this from deleting other resources like research or brand names. The resource is unambiguous even without reading sibling names.

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

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

The description implies this tool is for deleting deep dives and explicitly states an important prerequisite: the authenticated user must own the parent research. However, it does not explicitly mention alternatives or when NOT to use this tool. The ownership and irreversibility constraints give context but not full usage 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?

Beyond the destructiveHint and readOnlyHint annotations, the description adds critical behavioral details: the operation is irreversible, it cascades to linked deep dives, and it is restricted to owned research. This is exactly the kind of context an agent needs before invoking a destructive 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: the core action appears first, followed by necessary caveats. Every sentence adds value, covering cost, ownership, cascade behavior, and irreversibility without unnecessary detail.

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

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

For a simple one-parameter delete operation with no output schema, the description is complete. It covers what is deleted, who can delete it, what else gets deleted, and that the action cannot be undone.

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 fully documents the single `id` parameter with type, format, pattern, and a description. The tool description adds little parameter-specific meaning beyond saying 'by ID,' so the baseline score of 3 applies.

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

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

The description states a specific action, 'Delete a specific research by ID,' with a clear resource and identifier. It distinguishes itself from sibling tools like delete_deep_dive and delete_brand_names by naming 'research' as the target resource.

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 usage context: it can only delete research owned by the authenticated user, and it mentions the cascade behavior for linked deep dives. It does not explicitly name alternatives or say when not to use it, but the ownership restriction effectively defines a boundary.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description still adds real value by disclosing the returned payload (names plus domain, availability, price, and companion/TLD variants). No auth or rate-limit detail, but nothing contradicts the 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?

A single sentence, front-loaded with the action and identifier, then the return contents. No padding or redundant restatement of the title.

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

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

With no output schema, the description must describe returns and does so reasonably well, though the internal shape of a 'name' entry (price currency, availability values) is only gestured at. For a one-parameter read tool, this 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?

There is a single parameter with 100% schema description coverage (uuid-formatted run ID), so the schema carries the semantics. The description only says 'by id' and adds no format or sourcing guidance beyond the schema — the baseline 3 is correct.

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 precise verb and resource ('Get one brand-name run by id') and scopes it to a single run, which cleanly separates it from the plural sibling list_brand_names. The clause after the colon enumerates what comes back, so an agent knows the tool's shape 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?

Usage is implied by 'by id' — fetch the details of one already-existing run — but the description never states when to prefer this over list_brand_names or the per-domain checker, nor any prerequisite. Adequate but leaves routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds return-value context ('full analysis text'), which meaningfully supplements the missing output 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?

One compact sentence with the resource and scope front-loaded and 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 simple single-parameter read tool with full annotation coverage, the description says enough: what it fetches, how it is keyed, and what the response contains. Only a note on error behavior (e.g. unknown ID) is absent.

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

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

Schema description coverage is 100% for the single 'id' parameter, so the schema already documents it fully. The description's 'by ID' adds no syntax or format detail beyond that baseline.

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

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

States a specific verb (get) and resource (deep dive) scoped by ID, plus what it returns (full analysis text). This distinguishes it from list_deep_dives and create_deep_dive, though it doesn't name a sibling explicitly.

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: retrieve one deep dive when you already have its ID, in contrast to list_deep_dives. But there is no explicit when-to-use/when-not-to-use statement or named alternative, leaving the routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only "including full results," hinting the payload is heavyweight, but says nothing about pagination, size limits, or not-found behavior.

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

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

A single front-loaded sentence with no redundant or filler content, appropriately sized for a one-parameter lookup 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?

For a read-only single-ID getter with full annotation coverage, complete schema descriptions, and no output schema, the description is nearly complete; the mention of "full results" gives a rough sense of the return. The missing element is any hint about failure modes or result size.

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

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

Schema description coverage is 100% and the sole parameter's UUID format/pattern is fully specified in the schema, so the description carries no additional parameter burden. Baseline 3 applies since it adds nothing 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?

States a specific verb and resource ("Get detailed information about a specific research") scoped by ID, so the intent is unambiguous. It does not, however, distinguish itself from siblings like get_deep_dive or list_researches, so it falls 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?

The phrase "by ID" implies usage (you need an existing ID, presumably from list_researches), but no explicit when-to-use, prerequisites, or named alternatives are given. Usage is inferable 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?

Annotations already declare this a safe, non-destructive, non-open-world read, so the safety profile is covered. The description adds the shape of what comes back (id, target, created, name count, status), which is useful, but says nothing about ordering, pagination, or empty-result behavior 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?

Two sentences with zero filler; the scope of the operation is front-loaded before the return columns. Every clause carries information the agent can act on.

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 one-parameter read-only list tool with no output schema, the description supplies both the scoping rule and the returned columns, which is most of what an agent needs. The only real gap is list behavior (ordering, pagination) and the boundary with get_brand_names.

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

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

Schema description coverage is 100%, so the single researchId parameter is fully documented as 'The research ID whose brand-name runs to list'. The description restates the parent-scoping idea but adds no format or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (brand-name runs) scoped to a parent research, and clarifies the one-to-many relationship ('a research can hold several'). It does not explicitly distinguish itself from the sibling get_brand_names, which is the main ambiguity an agent would face.

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 by 'for a specific research' rather than stated as a condition. There is no mention of when to use this versus get_brand_names or create_brand_names, nor any prerequisites, so the agent must infer routing from names alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and a closed-world scope, so the safety profile is covered. The description adds one behavioral fact not in annotations — the return shape, 'a formatted table' — which is useful given there is no output schema, but it omits pagination/ordering behavior.

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

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

Two short sentences, no filler, and the scope constraint is front-loaded. The second sentence, disclosing the return format, earns its place since there is no output schema.

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

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

For a simple single-param list tool with annotations covering safety and a description noting the return format, this is largely sufficient. The only gap is the absence of any hint about ordering or empty-result behavior, which is minor here.

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

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

Schema description coverage is 100% and the single researchId parameter is fully documented in the schema. The description's 'for a specific research' simply restates the schema's meaning without adding format, constraints, or examples, so the baseline 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 clear verb (List), resource (deep dives), and scope (for a specific research), which separates it from the singular get_deep_dive sibling. It does not explicitly name or contrast against a sibling, so it stops short of the top band.

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?

There is an implicit condition — you must have a specific research in hand — but no explicit when-to-use, when-not-to-use, or guidance distinguishing this from get_deep_dive (single) or the other list_* tools. The agent is left to infer the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds two useful facts not in the structured data: results are scoped to the authenticated user and returned as a formatted table (output shape, which matters since there is no output 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?

Two short sentences, front-loaded with the core action and scope, and the return format is appended last. No filler and nothing 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?

For a simple two-parameter read tool with full annotation coverage and no output schema, the description covers the essentials: scope, pagination, and return format. Minor gaps remain — result ordering, behavior on empty results, and how it relates to list_deep_dives/list_brand_names.

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

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

Schema description coverage is 100% (limit with default 20/max 100, offset with default 0), so the schema fully documents both parameters. The phrase 'pagination support' merely restates the schema without adding syntax, ordering, or bounds details.

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

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

States a specific verb (List) and resource (researches) and scopes it to 'the authenticated user'. It does not, however, differentiate itself from siblings like list_deep_dives or get_research, so the agent must infer which listing tool applies to which resource.

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: listing is the natural read counterpart to create_research/delete_research, and 'pagination support' hints at large result sets. There is no explicit when-to-use, no pointer to get_research for a single item, and no exclusions.

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

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

Annotations are all false, so the description carries the behavioral burden. It usefully discloses that the retry is free because the credit was already charged, and that it returns the full regenerated analysis. It does not fully clarify whether the retry modifies the existing deep dive or creates a new one, but the provided behavior is still materially helpful.

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

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

Two sentences deliver the core purpose, the trigger condition, the cost behavior, and the return value with no filler. The most decision-relevant information 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?

With one documented parameter, a clear condition, cost disclosure, and a stated return value, the description is complete for this low-complexity tool. The absence of an output schema is adequately compensated by 'Returns the full regenerated analysis.'

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 documents the single id parameter with 100% coverage, so the baseline is 3. The description reinforces that the ID refers to a deep dive whose generation did not complete, but it does not add new parameter detail 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 states a specific verb (retry), a specific resource (deep dive), and the precise condition under which it applies (generation did not complete: failed or stuck without a result). It also distinguishes the tool from the sibling retry_research by naming the deep dive resource explicitly.

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

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

The description clearly tells when to use the tool: when a deep dive generation failed or is stuck without a result. It does not explicitly name retry_research as the alternative for research retries, but the resource distinction is apparent enough that an agent can infer the correct use case.

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

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

The description adds valuable behavioral context beyond the annotations: it is free because credit was already charged, it returns the compact summary shape of create_research, and it points to get_research for full reports. These details do not contradict the annotations.

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

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

Two sentences, front-loaded with the core purpose and then covering cost and output routing. Every sentence earns its place with no redundant wording.

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 retry operation, the description covers the triggering status, cost behavior, return summary, and follow-up path to get_research. Combined with the output schema and annotations, nothing essential is missing 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 input schema already describes the single id parameter with 100% coverage, including format and a clear description. The tool description adds no additional parameter-level meaning, which is acceptable but not enriching.

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 ('retry') on a specific resource ('research') and scopes it to research whose generation failed or is stuck. It also distinguishes the tool from siblings by noting its return matches create_research and that full reports come from get_research.

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 defines when to use the tool ('status failed, or stuck without a result'), clarifies that no additional credit is charged, and directs agents to get_research when a full report is needed. This gives clear decision guidance versus alternative tools.

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

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

The description goes well beyond the annotations by disclosing deduplication ('names not already shown'), non-destructiveness ('nothing is removed', consistent with destructiveHint=false), zero cost ('Free'), a rate limit ('capped at a few rounds per run'), a way to know the remaining rounds, and the return shape ('Returns the run with its new names'). This is rich behavioral context for an agent. No contradiction with annotations found.

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 is front-loaded in the first sentence, and every sentence contributes useful information (purpose/dedup, cost, cap, return). The cap sentence is slightly verbose ('so you never have to hit the cap to find out') and could be tightened, but overall the description is efficient and well-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 tool with one parameter, no output schema, and annotations present, the description covers all essential aspects: purpose, dedup behavior, non-destructiveness, cost, rate-limit handling, and return value. There is no output schema, so the description's explanation of 'Returns the run with its new names' is critical and provided. 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 description coverage is 100% — the single `id` parameter is already documented as 'The brand-name run ID to extend', which fully conveys its meaning. The description's phrase 'existing brand-name run' reinforces this but adds no new syntax or format details, so the baseline 3 for high schema coverage is appropriate.

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

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

The description uses a specific verb ('append') and resource ('an existing brand-name run'), and clarifies the scope ('a fresh batch', 'names not already shown'). It clearly distinguishes itself from create_brand_names (which starts a new run) and get/list_brand_names (which read), so an agent can route correctly without opening sibling 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?

The phrase 'existing brand-name run' clearly signals this tool is for extending an already-created run, which implicitly excludes create_brand_names as the alternative for starting fresh. However, it does not explicitly name sibling alternatives or state 'use X when you need to start a new run', so the guidance is implied rather than explicit.

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