Blackwood State

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses commercial and operational traits the annotations cannot: 0.02 USDC per call, p95 latency of 4000 ms, and the limitation that registrant personal data is redacted by registries. Those are exactly the behavioral facts an agent needs for cost/retry planning.

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, each load-bearing: one for the payload, one for use/don't-use routing, one for price and latency. The payload enumeration is front-loaded and no sentence is redundant.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still summarizes the payload sections. Combined with the cost, latency, redaction caveat, and routing guidance, 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% with only two parameters, both fully documented in the schema (including the 'true when omitted' default for certificates). The description mentions certificate transparency output, which loosely motivates the certificates flag, but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a precise verb-and-resource statement ('Returns JSON with a domain's registration...') and enumerates the exact payload sections: RDAP registrar/dates/status/DNSSEC, DNS records, SPF/DMARC, and TLS certificates. An agent knows exactly what this tool produces without opening the schema, and the 'Do not use' clause keeps it distinct from port/vuln scanners.

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 an explicit positive trigger set ('whois or domain lookup, dns records, email security checks or certificate transparency data for osint or due diligence') and an explicit negative set ('historical whois, registrant personal data, or a port and vulnerability scan'). Both when-to-use and when-not-to-use are spelled out, leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context annotations cannot carry: cost (0.005 USDC per call), p95 latency (800 ms), and a hard capability boundary (no SMTP probe, so mailbox existence is not confirmed). That capability limit is the single most decision-relevant behavior for this 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?

Front-loaded with the returned fields, then usage, then caveats, cost and latency — no filler sentences. The opening enumeration of return fields is partly redundant with the existing output schema, which is the only real slack.

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

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

With an output schema, full parameter coverage, and annotations covering the safety profile, the description fills the remaining gaps an agent needs: scope limits, cost, and latency. Nothing required to select or invoke 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?

One parameter with 100% schema description coverage, including an example and length bounds, so the schema carries the burden. The description adds no syntax or format detail beyond what the schema already states; 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 and resource ('Returns JSON with an email address check') and enumerates the exact facets checked (syntax, MX, disposable/free/role flags, SPF/DMARC, deliverability verdict). This is clearly distinguishable from every sibling, none of which validate email addresses.

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 ('before sending, signup or lead scoring') and when-not-to-use ('no SMTP probe is done', 'not to send email'). The exclusion of mailbox-existence checking is exactly the boundary an agent would otherwise get wrong.

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 the safety profile (readOnly, non-destructive, idempotent, open-world); the description goes well beyond by disclosing the async contract (jobId plus free pollUrl), cost (0.03 USDC per call), and latency (10000 ms p95). Output format (base64 JPEG) and provider/model are also given, which materially affects how an agent must handle the response.

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 output contract and model, then usage, exclusions, price, and async timing — every sentence carries distinct operational information with no filler. Dense but not padded.

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?

Although an output schema exists (so return values needn't be spelled out), the description still explains the async handoff and pricing, and covers everything needed to invoke and follow up on the job. No material gap remains for a two-parameter generation 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% and both parameters (prompt, steps) are already documented in the schema with ranges and defaults. The description adds no further meaning about parameter syntax or interaction, so the baseline 3 applies.

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

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

States a specific verb+resource with full detail: generates a 1024x1024 JPEG from a text prompt via FLUX.1 schnell on Workers AI, returned as base64 JSON. It also implicitly separates itself from the sibling image-gen_v1_status by noting the call is asynchronous and returns a jobId to poll.

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 when' clause (image generation/text-to-image for illustrations or mockups, and you can poll an async job) followed by an explicit 'Do not use when' clause listing four exclusion conditions (image edits, specific size, photos of real people, more than one image per call). This is exactly the when/when-not routing an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new context: the call is free, it returns a result as well as status, and the termination condition is the 'done' flag. It does not mention polling cadence or rate limits, which would be the remaining useful detail.

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

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

Three short clauses, front-loaded with the cost note and the resource identity, then the polling instruction. Nothing is padded and nothing important is buried.

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

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

Output schema exists, so the return payload (including the 'done' flag referenced) need not be re-explained. Cost, prerequisite tool, and polling behavior are all covered; the definition gives an agent 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 0% and there is one parameter, but the description hints at the provenance of jobId ('a job created by image-gen_v1'), which is more than the bare schema says. It still doesn't state the id format, lifetime, or what happens with an unknown/expired id.

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

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

The description names the specific resource (status and result of a job) and ties it explicitly to the sibling tool that creates the job, image-gen_v1. An agent can immediately tell it apart from image-gen_v1 itself and from unrelated status siblings like llm-chat_v1_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?

It states the calling pattern clearly ('Poll until done is true'), which tells the agent this is a follow-up call to a previously submitted job rather than an entry point. It stops short of explicitly naming when not to call it (e.g., that it only works on jobIds from image-gen_v1, not other tools' jobs).

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 (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: async job mechanics (jobId + free pollUrl), typical latency (8000 ms p95), and full pricing (0.002 USDC/1k tokens, 0.03 cap). This is exactly the kind of operational detail an agent needs before calling a paid async endpoint.

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 return value, then usage, exclusions, pricing, and async mechanics in tight sentences. The pricing parenthetical ('clients without upto pay the cap') is slightly cryptic, keeping it just under 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?

For an async paid LLM endpoint, the description covers the model, output, usage boundaries, pricing, and polling workflow; annotations cover safety and an output schema exists for return values. 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 the schema already documents messages, maxTokens, and temperature in detail, including defaults and bounds. The description adds no parameter-specific syntax or semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('chat completion'), names the exact backend model ('IBM Granite 4.0 Micro on Workers AI'), and discloses the return payload ('JSON ... with token usage'). It is clearly distinguishable from the sibling llm-chat_v1_status and the other domain tools.

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

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

Gives explicit when-to-use ('summaries, extraction or classification and can poll an async job') and explicit when-not-to-use ('frontier model, tool calling or streaming'). The alternative condition is fully spelled out, 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 already establish the safe-read profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds genuinely new context: the call is free, and there is a boolean done field to poll against, both of which tell the agent how to behave.

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

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

Three short sentences, front-loaded with the cost attribute and the polling condition. Every sentence conveys actionable information with no filler, though the one-word "Free." opener is terse rather than integrated.

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

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

An output schema exists, so return-value documentation is not required, yet the description still flags the done field, which is the key contract for polling. Combined with cost and provenance, it is sufficient for a one-parameter polling tool.

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

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

Schema coverage is 0% for the single jobId parameter, so the description must compensate. It does partially by tying the job to llm-chat_v1's creation, implying where to obtain the ID, but never states the expected format or that it is required.

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

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

States a specific resource (status and result of a job) plus the owning tool (llm-chat_v1), which cleanly distinguishes it from the sibling llm-chat_v1 that creates the job. An agent knows exactly what this returns 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?

"Poll until done is true" gives explicit polling guidance tied to the async llm-chat_v1 flow. It implicitly establishes the prerequisite (a job must exist) but never states the call ordering or that a done=false response means retry, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description's main added value is operational: cost (0.008 USDC per call), p95 latency (600 ms), the GDELT data origin, and the hard 72-hour recency ceiling. Those extras are genuinely useful for planning a call. It does not add anything about result completeness, deduplication, or rate limits beyond cost, so it stays at solid-but-not-rich.

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 return shape, then use/when-not, then cost and latency — a sensible priority order for an agent deciding whether to call. Three dense sentences, no filler, no repetition of the tool 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?

An output schema exists, so the description is not obligated to explain return values (though it briefly does). Combined with 100% schema coverage, full annotations, and disclosed cost and latency — the three things an agent cannot get from structured fields — the definition is complete enough to call correctly without further discovery.

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 all five parameters including defaults, ranges and the enum. The description reinforces the recency cap and that `query` matches across headlines, people and organizations, but adds no syntax or format detail the schema lacks. Baseline 3 plus a small lift for tying the description's 72-hour rule to the `hours` 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 and resource ('Returns ... recent news articles'), names the upstream source (GDELT), and enumerates the returned fields so the agent knows exactly what it gets. No sibling overlaps: the other tools are email, image, LLM, PDF, SEC, speech, wallet, weather and web tools, none of which return news.

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 ('news articles or headlines from the last 72 hours about a topic, company or person') and an explicit when-not list (full article text, paywalled sources, non-English coverage, news older than 72 hours). The 72-hour boundary is repeated and matches the hard maximum on the `hours` parameter, so the exclusion is enforceable rather than aspirational.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive); the description goes well beyond that with pricing (0.01 USDC/page, 0.2 USDC cap, upto behavior), async job semantics with jobId/pollUrl, and p95 latency of ~10000 ms. It also discloses hard functional limits (no OCR, no password-protected files, 15 MB ceiling) that 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?

Information-dense with no filler, and each sentence carries a distinct fact (return shape, usage, exclusions, cost, async contract). It opens with the return value rather than the core action and the pricing/async clauses are packed, but nothing is redundant.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes them helpfully. Combined with cost, latency, async polling contract, size cap and the three unsupported-input cases, an agent has everything needed to decide and to call correctly.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents the URL format and the 15 MB limit. The description repeats the size constraint but adds no new parameter-level syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Specific verb+resource ('Returns JSON with the text of each page of a PDF... plus title, author and producer metadata') with concrete scope (first 20 pages). It is clearly distinguishable from the polling sibling pdf-text_v1_status because the description states the paid call returns a jobId and a separate pollUrl.

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 positive trigger ('Use when you need to extract text from a pdf for document parsing, search or an LLM and can poll an async job') and explicit exclusions ('Do not use when the PDF is scanned (no OCR), password protected or over 15 MB'). The polling requirement effectively names the alternative path (pollUrl / status sibling).

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 read-only, idempotent, and non-destructive, so the safety bar is low. The description adds two things beyond them: that the call is free/no-cost and that it must be polled until a 'done' flag is true, which is meaningful behavioral context for a long-running job 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?

Three short sentences, front-loaded with cost and purpose, and the polling instruction is stated plainly. 'Free.' is terse product framing rather than task detail, but it does convey cost relevance for a repeated-poll call, so it mostly earns its place.

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

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

An output schema exists, so the return shape (including the done flag and result) needn't be restated in prose. Combined with annotations covering side effects, the description is complete enough; a suggested poll interval or error-handling note would round it out.

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

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

Schema coverage is 0% and the single jobId property has no description, so the description must carry the load. It partially does by implying jobId is the identifier returned by pdf-text_v1, but gives no format, source field name, or validity/lifetime guidance.

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

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

The description states the resource (job status and result) and ties it explicitly to the sibling that creates the job, pdf-text_v1, so an agent can tell it apart from the creation tool. It is a noun phrase rather than a crisp verb+resource, but the intent is unmistakable.

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

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

'Poll until done is true' gives an explicit operational instruction: call repeatedly, stop when the done flag flips. It also implicitly scopes usage to jobs created by pdf-text_v1. It doesn't state what to do on failure/error states, which keeps it from 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?

Annotations already establish readOnly/idempotent/non-destructive/closed-world, and the description adds context the annotations cannot: per-call cost (0.02 USDC), p95 latency (300 ms), and the exact temporal scope of the data (last two fiscal years). Cost and latency disclosure are material to invocation decisions and appear nowhere in 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 what is returned, then usage, then exclusions, then cost/latency. Every sentence carries distinct decision-relevant information; 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?

Output schema exists, so return-value explanation is not required, yet the description still enumerates the key fields. With cost, latency, temporal scope, and exclusions all stated, 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% and the single ticker param is well described, so the baseline is 3. The description goes slightly further by constraining valid tickers to US-listed SEC filers and excluding non-US companies, giving the parameter meaning beyond its regex pattern.

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?

Names a specific resource (annual revenue, net/operating income, diluted EPS, operating cash flow, year-end balance sheet) from SEC filings for a US-listed company, tied to an explicit input (stock ticker). No sibling operates in this domain, so no cross-tool disambiguation is needed beyond the scope statement.

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

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

Provides explicit 'use when' conditions (filings, earnings, fundamentals by ticker, last two fiscal years) and equally explicit exclusions (quarterly numbers, real-time prices, non-US companies, filings older than two years). An agent can decide fit without opening any schema.

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 (readOnly, idempotent, openWorld). The description goes well beyond: it discloses pricing model, per-call cap, async jobId/pollUrl pattern, and latency (p95 20s) — none of which are in annotations or schema. Strong added context.

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

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

Front-loads purpose, then usage, then pricing, then async behavior — a sensible priority order. Slightly dense with several distinct concerns in one paragraph, but no sentence is wasted.

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

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

Output schema exists, so return values need not be explained, and the description still previews the JSON shape. Combined with pricing, async lifecycle, and limits, an agent has everything needed to select 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%, so the baseline is 3. The description adds semantics the schema does not: the 10 MB size limit tied to the url parameter and the transcribe-vs-translate intent behind task. Marginal but real added 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 (transcription/translation) and resource (audio file) plus concrete output shape (text, timed segments, language). Clearly distinguishable from sibling pdf-text_v1 and from its own status 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?

Explicit when-to-use (transcription/translation of audio at a public URL) and when-not (audio over 10 MB, need for speaker labels). Names constraints that route the agent away correctly.

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

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

Adds key context beyond annotations: it's free, returns status and result, and requires polling until 'done'. Annotations already declare readOnly/idempotent, so the description's polling guidance is the real added value. Could mention error states.

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

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

Three short sentences, front-loaded with cost, purpose, and action. No wasted words, though 'Poll until done is true' could be tightened.

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

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

Given the existence of an output schema, the description needn't explain return values. It covers cost, relationship to sibling, and polling behavior – everything needed for an agent 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 coverage is 0% and one required parameter exists (jobId), but the description doesn't define it. Baseline 3 is appropriate since schema structure alone doesn't add semantic meaning, though the parameter itself is self-explanatory from name.

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 (status/result) and resource (job created by speech-to-text_v1), and clearly distinguishes itself from the sibling speech-to-text_v1 by referencing it as the creator.

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 says 'Poll until done is true,' telling the agent exactly when and how to use this tool relative to the synchronous sibling.

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 readOnly/idempotent/non-destructive/open-world, and the description still adds material context beyond them: a per-call price (0.003 USDC), p95 latency (1200 ms), the data source (Uniswap v3, USDC/WETH quotes), and an explicit coverage limitation (Aerodrome is not read). This is exactly the value-add expected on top of annotations.

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

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

The core behavior is front-loaded in the first clause, then usage, exclusions, cost, and latency follow in compact sentences. No filler or redundancy.

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

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

With an output schema present, the description need not spell out return values, yet it still hints at them ('with pool, fee tier and depth'). Cost, latency, source, and coverage limits are all disclosed, which is everything an agent needs to call this correctly.

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

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

Schema description coverage is 100% and the single 'token' parameter is already documented with accepted forms (0x address or symbol examples). The description restates 'token on Base' but adds no syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Returns JSON with the USD price of a token on Base') plus the exact computation method (deepest Uniswap v3 pool against USDC or WETH). No sibling tool does anything similar, so it is trivially distinguishable from wallet-balances_v1 or sec-facts_v1.

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 ('crypto token price or market data for a Base token, quoted from on-chain liquidity') and explicit when-not ('token only trades off Base or on other DEXs (Aerodrome is not read), or you need history or OHLC'). 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 already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds genuinely new operational facts: a price of 0.004 USDC per call, p95 latency of 1200 ms, and that balances are read in a single block (an atomic snapshot). It stops short of describing failure modes or rate limits, so it is strong but not exhaustive.

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 return shape, then usage, then exclusions, then cost and latency. The 'Use when you need the ERC20 token balance or wallet balance...' clause partially restates the opening sentence, which is the only real 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?

An output schema exists, so return values need not be detailed, and the description still summarizes the payload. Combined with cost, latency, chain scope, default token set, and explicit exclusions, an agent has everything needed 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 baseline is 3. The description adds meaning beyond the schema by disclosing that 21 major tokens are queried by default, which explains the semantics of the optional 'tokens' array as an additive list rather than a filter.

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: returns ETH and ERC20 token balances for a wallet on Base, read on-chain in one block. It is clearly distinguishable from siblings like token-price_v1 (prices, not balances) and explicitly scopes itself to Base.

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 when-to-use condition ('need the ERC20 token balance or wallet balance of an address on Base for onchain data checks') and an explicit when-not list (Ethereum mainnet or other chains, NFTs, transaction history, USD values). This is exactly the routing information an agent needs against the sibling set.

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 read-only/idempotent/open-world safety, and the description adds information the annotations cannot: cost (0.003 USDC per call), p95 latency (1500 ms), source attribution and the coordinate input requirement. It does not describe forecast granularity or max horizon, though the schema parameter does.

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 return payload, then use/do-not-use, then cost and latency – a sensible order. Slightly dense with the field enumeration, but every clause carries operational value.

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

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

An agent has everything needed: what it returns, coordinate constraints, when to pick an alternative, the geocode prerequisite, cost, latency and a full output schema. No material gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds the coordinate framing and notes place names must be geocoded first, which clarifies that no name parameter exists anywhere.

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 (returns) and resource (hourly weather forecast), enumerates the returned fields, names the data source (MET Norway), and distinguishes its scope from siblings by ruling out historical weather and alerts.

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 says when to use ('weather forecast, temperature or precipitation for the next hours or days at a place given by coordinates') and when not to use (historical weather, severe alerts, place names), plus the remediation: geocode the name first.

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 readOnly/idempotent/openWorld semantics, so the safety profile is covered; the description goes further by disclosing cost (0.01 USDC per call), p95 latency (2500 ms), and the concrete failure modes (no JS rendering, no paywall/auth, HTML only). That is behavioral context an agent cannot get from 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?

It is compact and dense: return shape, usage, exclusions, price, and latency each occupy their own sentence with no filler. Minor redundancy in the triple synonym 'scrape a web page, extract content from a url or read an article', and the leading sentence describes returns before the action, costing it the top score.

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

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

With an output schema present and annotations covering safety, the description needs only routing, cost, and latency to be complete for a two-parameter read tool — and it supplies all three plus the limitations. An agent has everything needed to decide whether to call it and what to expect.

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 both parameters, so the schema already documents the URL format and the maxChars range/default. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb+resource (fetch a public web page and return clean Markdown) and enumerates the payload (title, description, language, canonical URL, links). It also draws a clear boundary against the nearest sibling by name of function ('use a PDF reader for PDFs'), so an agent can distinguish it from pdf-text_v1 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?

It states explicit use cases ('scrape a web page, extract content from a url or read an article as markdown for an LLM') and explicit exclusions (JavaScript-rendered pages, login/paywall, non-HTML content) with a routing hint to the PDF alternative. Both the when and the when-not are spelled out rather than implied.

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