Suprsonic

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds genuinely new context: the return format is a base64 transparent PNG, and the cost is 2 credits charged only on success. That cost/billing disclosure is exactly the kind of behavior annotations cannot express; it stops short of 5 only because no failure modes or input constraints are described.

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?

Short and front-loaded, but the second and third sentences restate the same fact twice ('Returns transparent PNG' / 'Returns the cut-out as a base64 PNG with a transparent background'). One of those sentences does not earn its place, costing conciseness.

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 explain return values and it does (base64 PNG with transparency), plus it discloses billing behavior. What remains missing is any note on input constraints (URL accessibility, supported formats), which matters for a remote-fetch image tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured data, and the description adds no detail about image_url format or the 'size' enum (auto/small/hd). Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb+resource ('Remove background from any image') and immediately defines the output ('transparent PNG'). It also distinguishes itself from the sibling 'images' tool by scoping itself to existing images, so an agent can route without opening either schema.

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

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

Gives a clear usage context ('Use to isolate the subject of an existing image') and an explicit alternative with its selecting condition ('To create a new image use images'). No exclusions or input-format constraints are stated, so it falls just short of a 5.

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

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

Goes well beyond the annotations by disclosing ephemerality ('fresh sandbox... destroyed afterwards, so nothing carries over'), the cost model ('2 credits, charged only when a call succeeds'), and the exact return payload (stdout, stderr, exit code, run time, files written to /home/user/output/). The non-idempotent, non-persistent nature is spelled out rather than 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?

Front-loaded with the core action and return contract, followed by use cases, sandbox lifecycle and cost — every sentence carries information. The sandbox-lifecycle sentence is slightly redundant in phrasing ('fresh sandbox... destroyed' vs 'nothing carries over'), a minor inefficiency.

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 compensates by enumerating the return fields, and it covers the non-obvious traits an agent needs (ephemerality, cost-on-success, output path). For a 4-parameter execution tool this is complete.

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

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

Schema description coverage is 100%, so the schema already documents code, timeout, language and template including enum values. The description only alludes to templates ('pre-configured environments') and the output directory, adding little syntax or default detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Execute code in a secure sandbox with pre-configured environments') plus the concrete return payload, so the agent immediately knows this is the general-purpose code runner rather than any of the media/data siblings. No sibling overlaps with arbitrary code execution.

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?

'Use for calculations, data processing and running scripts' gives clear positive context for when this tool is appropriate. It does not, however, name any exclusions or alternatives (e.g. when a dedicated sibling like file-convert or invoice-parse is preferable), so it falls short of the top tier.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and open-world scope are covered. The description adds genuinely useful non-annotation context: a fixed cost of 3 credits charged only on success. It doesn't discuss rate limits, failure modes, or caching, but the cost/billing disclosure is meaningful added value over the structured fields.

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

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

Three front-loaded sentences: purpose, usage/exclusions, then cost. Every sentence carries information the agent needs, and nothing is repeated from the schema or annotations.

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

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

There is no output schema, and the description compensates by enumerating the return contents (name, description, industry, size, founding year, HQ, employees, revenue, funding, social links, technologies, logo, brand colors). Combined with usage boundaries and cost, an agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100% with only two parameters, both already described ('Company domain.', 'Optional name hint.'). The description's 'by domain' reinforces that domain is the lookup key but adds no format, normalization, or hint-behavior detail beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb+resource and scope: 'Enrich company data by domain.' It then enumerates the returned fields, making the tool's offering concrete. It also explicitly names what it is not (site-intel for technical domain facts, profiles for people), so an agent can separate it from siblings without opening 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?

'Use for business facts about a company' gives the affirmative trigger, and the two exclusion clauses route the agent to site-intel for WHOIS/DNS/SSL/hosting and profiles for a person. This is explicit when-to-use plus named alternatives — the top of the scale.

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 cover the safety profile (readOnlyHint, openWorldHint), but the description adds real behavioral context: JSON output shaped by the schema, inclusion of the source URL and a truncation flag, and a cost model (3 credits, charged only on success). It stops short of describing failure behavior or rate limits, so 4 rather than 5.

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

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

Front-loads the purpose, then usage/routing, then parameters and cost. Dense and mostly waste-free, though the final two sentences could be tightened into one without losing information.

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

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

With no output schema, the description carries the return-value burden and does so by naming the JSON payload, the source URL, and the truncation indicator. Combined with the cost disclosure, an agent has enough to call it correctly; only error/auth behavior is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantic relationships: 'Pass url or content' implies the source alternatives, and it explains that extraction_prompt defines what to extract while schema fixes the output shape. This clarifies the interplay of the parameters beyond their individual schema descriptions.

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

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

States a specific verb (extract) and resource (structured data from URLs or content), and explicitly differentiates from siblings 'scrape' and 'invoice-parse' by naming their use cases. An agent can select this tool without opening any schema.

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

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

Names alternatives and the exact conditions that route to them: full page text to scrape, invoices/receipts to invoice-parse. Also states the positive case ('turn a page or a text into structured fields'). No inference required.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by stating there are no purchase side effects ('never registers or buys'), giving per-mode credit costs, and specifying credits are 'charged only when a call succeeds' — exactly the billing behavior an agent needs before firing a paid call.

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

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

Front-loaded with purpose, then modes, then the boundary, then the mode/field map, then cost — a sensible ordering for a six-mode tool. It is dense and long, but for an 11-parameter multi-mode tool nearly every clause carries decision-relevant information; only the enumerated return list is mildly redundant with the schema.

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

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

No output schema exists, so the description carries the return burden and does so per mode ('name ideas with prices, extensions that fit with reasons, one name across extensions, availability...'). Combined with cost, side-effect, and mode/param guidance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter semantics the schema cannot express: 'mode decides which fields apply: company_name and description for the suggest modes, query for search-extensions, domains for check-availability, tlds for pricing.' It stops short of covering offset, exact_extension, or the precedence rules already 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?

Opens with a specific verb+resource ('Find domain names and the extensions that fit a business') and then enumerates what each of the six modes returns, so an agent can map intent to mode without opening the schema. It also explicitly demarcates itself from the sibling site-intel ('for facts about a domain that is already live').

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

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

States the when ('to name a business or check domains before buying one'), the when-not ('it never registers or buys a domain'), and the alternative for the adjacent need (site-intel for live-domain facts). The mode-to-field mapping further tells the agent which mode to select for which job.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured context: the confidence scale (0 to 1), the verification status, and the cost model (2 credits, charged only on success), which is material for an agent deciding whether to call. It stops short of auth requirements or rate limits.

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

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

Four short sentences, front-loaded with the purpose, then return values, then routing to alternatives, then cost. Every sentence carries distinct information with no repetition of the name or 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?

There is no output schema, but the description compensates by describing the return fields directly (address, confidence, verification status). Combined with the routing guidance and cost note, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% with all four parameters described, so the schema carries the parameter burden and the baseline is 3. The description adds framing (a person's work email at a company) but no syntax or format guidance 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 ("Find professional email addresses") scoped to a named person's work email at a company, which cleanly separates it from sibling search/profiles tools. It also states the return shape (address, confidence, verification status).

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

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

Explicitly names both alternatives and the condition that selects them: "To check an address you already have use email-verify; for the person's background use profiles." No inference required.

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

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

Annotations only cover safety (readOnlyHint) and openness (openWorldHint), so the description correctly carries the rest: it enumerates the returned status, sub-status, free-mailbox flag, suggested correction, domain age, and mail servers, and discloses the cost model ('1 credit, charged only when a call succeeds'). It does not mention rate limits or authentication needs, but for a read-only lookup that is a minor gap.

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

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

Front-loads what the tool determines, then the return payload, then the usage rule and alternative, then the cost caveat. Every sentence carries distinct information with no 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?

There is no output schema, yet the description explicitly enumerates the response fields an agent needs in order to interpret results, and it covers the selection decision and cost. Nothing required to call or act on the tool 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or normalization guidance for the email input, which is the baseline-3 case.

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 (an email address) plus the exact judgment it renders — deliverable, catch-all, or disposable. It is clearly distinguishable from the sibling 'emails' tool, which is named directly.

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

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

Gives an explicit trigger ('Use before emailing an address you were given or found') and routes the agent away from this tool with a named alternative ('To find an address from a person's name use emails'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real value beyond them by disclosing the return payload (download URL, name, size, formats) and the cost model ('2 credits, charged only when a call succeeds'). It does not mention size limits, failure modes, or that 'web' sources are HTML-only without JavaScript (that detail lives only in 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?

Four tight sentences: purpose first, then return value, then usage and alternatives, then cost. Every sentence carries distinct information with no repetition of the title or 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?

No output schema exists, yet the description still summarizes the return shape (URL plus name, size, formats), and the schema fully documents inputs. Combined with the sibling routing and cost note, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so file_url, source_format, and target_format are already described in detail in the schema (including the web/HTML caveat and the ConvertAPI fallback). The description adds only illustrative pairs, not syntax or constraint detail, so baseline 3 applies.

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

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

Specific verb+resource: 'Convert documents, web pages, spreadsheets and images between formats.' Concrete examples (Word to PDF, PDF to Markdown) and explicit disambiguation from the 'documents' and 'scrape' siblings make it 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?

States when to use it ('to change a file's format') and names two alternatives with the conditions that select them: 'To extract specific fields use documents; to read a web page's text use scrape.' Nothing left to inference.

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

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

Goes well beyond the annotations: discloses cost (3 credits) and, critically, that it is 'charged only when a call succeeds', plus the exact return payload (hosted PNG URL, same image as b64_json, aspect ratio and size used). For a generation tool with no output schema, that return-shape and billing disclosure is exactly the context an agent needs.

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

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

Four tight sentences: purpose, payload, usage-plus-alternatives, cost. Nothing is redundant with the schema or annotations, and the routing information (bg-remove/screenshot) is front-loaded where an agent will see it before committing.

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 fully compensates by enumerating return fields; with annotations silent on billing, the cost model is spelled out. Nothing needed to invoke this correctly — purpose, inputs, outputs, cost, and sibling routing — 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% and both parameters are documented there, so the schema carries the semantics. The description confirms that aspect ratio and size come back from the call but adds no new detail about allowed values, defaults, or prompt constraints beyond the enum already in the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Generate images from text prompts') and immediately pins down scope against the two nearest siblings (bg-remove for background removal, screenshot for web capture). An agent can distinguish this from every sibling in the list without opening 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?

Explicit 'use to create a new picture from a description' plus two named alternatives with the exact condition that selects each ('cut the background out of an existing image', 'capture a web page'). This is the when/when-not/alternatives pattern at full strength.

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 and openWorldHint, so safety is covered. The description adds real value beyond them: a concrete cost ('3 credits, charged only when a call succeeds') and the full set of returned fields, which is meaningful since no output schema exists. It stops short of noting rate limits, input size limits, or failure modes.

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

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

Four short sentences, each doing distinct work: capability, return contents, usage scope, and cost. The core purpose 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?

With no output schema available, the description compensates by enumerating the returned fields, and it covers cost, input modality, and the sibling alternative. An agent has everything needed to decide and invoke correctly.

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

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

Only one parameter with 100% schema description coverage, so the schema already carries the meaning. The description restates the input modality ('PDF or image URL') but adds no format or size constraints beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb+resource ('Extract structured data from invoices and receipts') and enumerates exactly what is returned (invoice number, dates, parties, currency, totals, line items). It also explicitly distinguishes itself from the sibling 'documents' tool, so an agent can separate the two without opening 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?

Gives an explicit inclusion condition ('Use for an invoice or receipt given as a PDF or image URL') and an explicit exclusion routing to an alternative ('For any other document use documents with your own schema'). The when-not and the alternative are both 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?

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds a real behavioral fact beyond them: 3 credits charged only on success. It does not mention authentication requirements or rate limiting, but for a read-only lookup this is close to complete.

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

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

Front-loaded with purpose, then returns, then usage, then inputs, then cost — a sensible order. The returned-field enumeration is long but earns its place because no output schema exists. Minor redundancy between the 'find/enrich' framing and the field list keeps it short of perfect.

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 supplies the return shape, and with no required parameters it supplies the input combinations. Cost semantics, alternatives, and the read-only posture are all covered, so an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes further by specifying the valid input combinations ('Pass linkedin_url, or first_name and last_name; company helps find the right person') — a fact the schema cannot convey since it marks zero parameters as required. That is genuine additive value.

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 pair and resource ('Find and enrich professional profiles') and immediately enumerates the returned data, so an agent knows what it gets back. It explicitly contrasts itself with the 'emails' and 'companies' siblings, making disambiguation possible without opening any schema.

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

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

Gives explicit when-to-use ('learn who a professional is and what they have done') plus two named alternatives with the condition that selects each ('For their work email use emails; for a company rather than a person use companies'). It also states the viable input combinations, which is the actual usage guidance for a 0-required-parameter tool.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description goes well beyond by disclosing the full credit price ladder (10/20/35), that charges occur only on success, and per-option cost deltas (+5 analysis, +2 academic, -3 entity enrichment, -5 synthesis). It also discloses the return shape (title, summary, sections, key findings, confidence, numbered sources, enriched entities), which is rare and valuable.

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

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

Front-loaded with purpose and the sibling comparison before the cost detail, and every sentence carries information. The final cost sentence is a compressed run of plus/minus clauses that takes a second pass to parse, which is a minor readability cost but no wasted 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 an 8-parameter open-world tool with no output schema, the description covers what it returns, how long it takes relative to alternatives, what it costs under every option combination, and when to reach for it. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: credit cost per `depth` value and cost deltas tied to `include_analysis`, `source_types`, `enrich_entities`, and `synthesis`. The agent knows the budget consequence of each flag, not just its type.

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 multi-step verb chain (search, scrape, enrich, synthesize) and the deliverable (a cited report), and explicitly distinguishes itself from the sibling `search`, which 'suits a quick fact.' An agent can pick between them without opening either schema.

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

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

It gives the selecting condition ('a question that needs many sources and a synthesized, cited answer') and the inverse ('far longer and costs more than search, which suits a quick fact'), naming the alternative tool directly. Explicit when-to-use and when-not-to-use.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the rest and does it well: per-mode latency expectations are embedded, and the cost model is disclosed precisely ('fast 1 credit, standard 2 credits, thorough 5 credits, charged only when a call succeeds'). The charge-only-on-success detail materially affects how aggressively an agent retries or upgrades modes.

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

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

Front-loads purpose and return shape, then usage, then mode escalation, then sibling alternatives, then cost. Every sentence carries distinct information and nothing is repeated from the annotations or 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?

With no output schema, the description compensates by stating what is returned (content in the chosen format plus title, description and links), and it covers the operational concerns a 5-parameter open-world scraping tool raises: cost, latency per mode, and fallback routing to documents/screenshot.

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

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

Schema coverage is 100%, so the schema already documents each parameter's enum values and defaults; the baseline is 3. The description adds a decision rule not present in the schema ('start with fast', standard for JS-heavy pages, thorough only for scraper-blocking sites), which is actionable parameter guidance beyond the raw enum text.

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 ('Extract content from any URL as Markdown or HTML') and immediately distinguishes itself from siblings by naming documents and screenshot as the alternatives for those use cases. An agent can tell exactly what this tool produces without opening 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?

Gives an explicit trigger ('Use when you have a URL and need what the page says'), a mode-selection rule ('Start with fast; use standard for pages that need JavaScript and thorough only for sites that block scrapers'), and named alternatives for adjacent needs ('To pull specific fields into JSON use documents; to see the page as an image use screenshot'). This is when/when-not/alternatives in full.

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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description adds real value beyond them: the return payload shape (base64 + format, dimensions, size) and the billing trait ('Cost: 1 credit, charged only when a call succeeds'). It does not mention rate limits, timeouts, or failure modes for unreachable pages, which keeps it short of a 5.

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

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

Four short sentences, each earning its place: purpose, return shape, usage routing, cost. The purpose is front-loaded and the alternative is placed immediately after it.

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

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

There is no output schema, but the description compensates by describing the return (base64 image with format, dimensions, byte size). Combined with the credit-cost note and the scrape alternative, an agent has everything needed to call it correctly and interpret the result.

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 url, width, height, format and full_page, including the enum. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ('Capture a rendered screenshot of any webpage') that states exactly what the tool produces. It explicitly contrasts itself with the sibling 'scrape' (text vs. visual), so an agent can differentiate without opening either schema.

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

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

'Use to see how a page looks. To read its text use scrape.' gives both the when-to-use condition and the named alternative that selects a different tool. Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description's burden is lighter. It nonetheless adds real information beyond the annotations: the exact shape of results per mode ('title, url, snippet, position' plus knowledge graph/featured snippet), and a credit-cost model with the notable caveat that credits are 'charged only when a call succeeds.' Pagination and error/rate-limit behavior are the only material 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?

Three tightly packed sentences with zero filler, ordered purpose -> return shape -> routing -> cost. Every clause carries information an agent needs (mode outputs, sibling alternatives, per-call credits), so nothing is 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?

There is no output schema, and the description compensates by describing returns per mode. With annotations covering read-only and open-world semantics, all five parameters documented in the schema, and costs stated, an agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already defines every parameter. The description goes slightly beyond it by tying each mode value to a concrete output form (serp = organic results, ai = written answer with cited URLs, deep = both), which is the one piece of mode semantics the enum text only partially conveys.

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 ('Search the web') and immediately enumerates the three distinct modes (SERP, AI synthesis, both), so the agent knows exactly what capability is on offer. It also names the two nearest siblings (scrape, research) and the boundary condition that separates them, which is the strongest form of differentiation.

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

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

Gives explicit when-to-use ('current facts, news and finding pages') plus two named alternatives with their selecting conditions: 'To read one page in full use scrape; for a report built from many sources use research.' Nothing about routing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: per-mode credit costs and the fact that charges occur only on successful calls. It does not discuss rate limits or error behavior, so it falls short of the highest level.

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 definition is front-loaded with the core purpose, then covers returns, alternatives, and costs in a compact sequence. Every sentence adds decision-relevant 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?

With only two parameters, no output schema, and clear read-only annotations, the description is complete enough for correct invocation. It explains what each mode returns and what the costs are, so an agent does not need additional return-value documentation.

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

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

Schema description coverage is 100%, so the schema documents both parameters and the mode enum. The description goes beyond that by mapping each mode to its return data and cost, making the enum semantically meaningful rather than just a list of strings.

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 and resource ('Get comprehensive domain intelligence') and immediately enumerates the mode-specific outputs. It explicitly distinguishes itself from sibling tools by directing business-company questions to companies and registration-name searches to domains.

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 states when to use this tool ('technical facts about a domain') and names the exact alternatives for two adjacent use cases: companies for business facts and domains for finding a registrable name. The mode costs further help an agent choose the right depth.

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

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

Goes well beyond annotations: irreversibility ('cannot be recalled'), non-idempotency ('every call sends a new one'), the failure mode of WhatsApp (silently dropped by Meta), and the cost model (1 credit, charged only on success). These are exactly the operational facts an agent needs before invoking a real outbound send.

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

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

Four short sentences, front-loaded with the core action and default, then consequences and cost. No filler; each sentence carries a distinct operational fact.

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?

No output schema exists, so the description enumerates the return fields (message id, channel, recipient, sender number, status). Combined with the loss/cost warnings and annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the E.164 format, enum values, and default. The description restates the channel default and opt-in rule rather than adding new syntax or constraints, so baseline 3 applies.

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

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

Opening line states a specific verb (send) plus the two resources (SMS/WhatsApp) and immediately clarifies the default channel, so it is unambiguous against siblings such as emails or tts. An agent can distinguish it without opening 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?

Gives a direct when-to-use rule ('text a number the user gave you') and explains the conditions for the WhatsApp channel (recipient must have messaged within 24 hours). It does not explicitly mention alternative tools (e.g., emails for non-phone delivery), so it stops short of full alternative 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 only declare readOnlyHint and openWorldHint, so the description usefully adds the return shape (base64 audio plus format, sample rate, duration) and the billing behavior (4 credits, charged only when a call succeeds) — real operational context an agent cannot get from the annotations. It stops short of covering latency, max prompt length, or why a generation tool is marked read-only despite consuming credits.

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 front-loaded sentences covering purpose, return, and cost, each earning its place. The only waste is mild redundancy: the speech exclusion appears in the description and again in the prompt parameter's own schema text.

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

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

There is no output schema, so the description must carry return-value information — and it does, naming the base64 payload and the metadata fields, plus cost and the speech exclusion. Nothing essential for calling this four-parameter, one-required tool 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%, with the duration range (0.5–22), the format enum and the prompt_influence scale all documented in the schema, so the baseline is 3. The description adds no syntax or default guidance beyond what the schema already provides and repeats the 'not for speech' caveat already present on the prompt property.

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

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

States a specific verb+resource (generate sound effects and short music tracks from text prompts) and immediately draws the boundary against the closest sibling: 'NOT speech: use tts for spoken voice.' An agent can distinguish it from tts, stt and transcribe without opening any schema.

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

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

Explicitly names the positive use cases (sound effects, ambience, short instrumental music) and the exclusion with the alternative (no spoken words; use tts). The when-not condition and the substitute tool are both stated, leaving nothing 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 only declare readOnlyHint and openWorldHint; the description goes well beyond them, disclosing the full return shape (transcript, confidence, language, duration, per-word start/end times), the billing model (2 credits, charged only on success), and the two accepted input channels. That is exactly the behavioral context annotations cannot carry.

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

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

Purpose is front-loaded in the first sentence, return values second, routing guidance third, input and cost last. Every sentence carries distinct 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?

With no output schema, the description compensates by enumerating the return fields, and it covers cost, input channels, and sibling routing. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the audio_url vs audio_base64 choice as 'or', which adds mild clarity on input alternatives but no syntax, format, or size limits, and it says nothing about the language 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?

States a specific verb+resource ('Transcribe audio to text with timestamps') and immediately differentiates itself from the siblings transcribe and subtitle by naming both and the conditions that select them. An agent can route among the three transcription-family tools without opening any schema.

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

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

Explicit when-to-use ('a short clip whose exact words and timings you need') plus two named alternatives with their own selection criteria: transcribe for long multi-speaker recordings, subtitle for caption files. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description usefully adds the pricing model ('Cost: 2 credits, charged only when a call succeeds') and the return shape (SRT/VTT text plus language, duration, cue count). It stops short of media constraints (size/duration limits) but covers more than the annotations alone.

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

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

Four tight sentences with zero filler, front-loaded with the action and output, followed by usage and the alternative. Every sentence carries distinct information.

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

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

With no output schema, the description correctly compensates by describing the return contents (subtitle text, language, duration, cue count) and the billing behavior. Only minor operational details such as supported media limits or async/polling behavior are 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%, so all three params (format, language, audio_url) are already documented with defaults and an enum. The description restates that output comes in SRT or VTT but adds no parameter-level syntax or constraint beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource ('Generate SRT/VTT subtitles from audio or video') and immediately distinguishes itself from the transcription siblings. An agent can tell what this produces (caption files) versus a plain transcript without opening 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?

Gives explicit use context ('Use to caption a video or an audio file') plus a named alternative with the selecting condition ('For a plain transcript use stt or transcribe'). Both the when and the when-not are covered.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing the return payload (transcript, confidence, language, duration, word and speaker counts, per-utterance speaker/timing) and the billing model (3 credits, charged only on success). The only-succeeds-billing detail is genuinely decision-relevant information absent from structured fields.

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

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

Three sentences, front-loaded with the capability, followed by output shape and then cost/alternatives. No filler, and each sentence supplies a distinct decision input.

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 correctly assumes the burden of describing return values, and it also covers cost and sibling routing. Nothing an agent needs to select or invoke this tool is left unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents audio_url, language, and speaker_labels. The description mentions diarization and timestamps conceptually but adds no syntax, defaults, or format detail beyond what the schema carries.

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 ('Transcribe audio') plus the differentiating capability (speaker diarization and timestamps). It explicitly distinguishes itself from the nearby siblings stt and subtitle, so an agent can route correctly without opening any schema.

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

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

Names concrete scenarios (meetings, interviews, podcasts 'where who spoke when matters') and gives explicit alternatives with their selecting conditions: stt for short-clip word timings, subtitle for caption files. This is textbook when/when-not/alternative guidance.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false, so the description carries useful extra weight: it discloses the return payload (base64 MP3 with sample rate and voice used), the per-call character cap, and the cost model (2 credits, charged only on success). That covers the main behavioral unknowns for a paid generation call, though it says nothing about latency, timeouts, or failure modes.

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

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

Four short sentences ordered by importance: what it does, what comes back, when to use it (with the alternative), and the cost. No filler and no redundancy with the schema beyond the unavoidable character limit.

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 steps in to describe the return shape and the cost, and it names the sibling to route to for a different need. For a 3-parameter generation tool with full schema coverage and read-only annotations, 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%, so all three parameters are already documented in the schema, giving a baseline of 3. The description repeats the 2,000-character limit but adds no meaning for `provider` or `voice_model` (e.g., when deepgram vs elevenlabs is preferable), so it does not rise above 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+resource ("Convert text to speech audio") and immediately distinguishes itself from the closest siblings by name: sound-generate for effects/music and, implicitly, the transcribe/stt family for the reverse direction. An agent can classify this tool without opening 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?

Explicit when-to-use ("spoken voice or narration") plus an explicit redirect for the adjacent need ("For sound effects or music use sound-generate"). The 2,000-character ceiling and credit cost also set scope conditions for the call.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing link expiry (one hour), the metadata returned, the async job_id flow for long/YouTube downloads, and a cost model (3 credits video, 2 audio, charged only on success, job polling free). These are exactly the operational facts an agent cannot infer from structured fields.

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

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

Front-loaded with the core outcome and tightly packed with scope, async behavior, alternative tool, and cost. Minor redundancy in 'return a temporary download link. Returns a download link that expires after one hour,' which restates the same idea before adding the expiry.

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?

No output schema and no annotations covering the return payload, yet the description names the returned fields, the expiry, the async intermediate response, the polling contract, and the billing rules. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies the url-vs-job_id split (call again with job_id to collect an in-progress download) and ties the audio formats to the cheaper 2-credit tier. Quality/format enums themselves are left to 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 (download video from any URL) plus the concrete return artifact (temporary download link with name, size, duration, quality, format, title, thumbnail). It explicitly distinguishes itself from the sibling video-info tool, which returns details without a file.

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

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

Gives explicit when-to-use ('Use to get a video, or only its audio, as a file') and when-not ('For its details without downloading use video-info'), naming the alternative sibling. It also explains the async path: downloads over ~90 seconds answer status=processing with a job_id, and you call again with that job_id.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower; the description still adds real value by disclosing the billing model ('Cost: 1 credit, charged only when a call succeeds') and enumerating the returned fields. It lacks detail on failure behavior (what happens to the credit on error, unsupported URLs), keeping it just short of 5.

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

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

Three tightly packed sentences: purpose and returns first, then routing guidance, then cost. Every clause carries distinct 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?

With no output schema, the description compensates by listing the exact return fields (title, duration, thumbnail, uploader, upload date, view count, platform, formats with sizes), plus cost and routing. An agent has everything needed to call it correctly and interpret the result.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents 'url' fully. The description adds only a mild generalization ('any URL'), which is baseline-level value beyond structured data.

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 (Extract) and resource (video metadata, formats, thumbnail) from any URL, and explicitly names the sibling tools it is not (video-download, transcribe). An agent can distinguish this from the other 23 siblings at a glance.

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

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

Gives the when ('inspect a video before downloading it') and both alternatives with their conditions ('To get the file use video-download; for what is said in it use transcribe'). Nothing is left to inference for tool selection.

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