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

Annotations only declare readOnlyHint=true; the description goes well beyond by disclosing the 5 MB streamed cap, the default/max limit and the truncation flag, that all values are returned as strings, and that unknown select columns or bad filters produce errors listing valid names/operators. It also describes the return payload shape even though no output schema exists. It stops short of stating pagination or auth behavior for the forwarded headers, so not a full 5.

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

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

Front-loaded with the safety/size framing, then source modes, then capabilities, then return shape, then constraints, then the escape hatch to the paid sibling. Dense but every clause carries distinct information; 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 nine optional parameters, no output schema, and a nested headers object, the description still covers source modes, limits, error behavior, return structure and the upgrade path. Nothing an agent needs to 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?

Schema coverage is 100%, so every parameter already carries its own description including the filter operator list and enum values. The description largely restates these (mutual exclusivity of csv/url, limit behavior, filter restrictions) rather than adding syntax or edge-case guidance the schema lacks. 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 (query) and resource (CSV with a header row) plus the exact operations available: select, filter, sort, limit. It also distinguishes itself from the paid sibling csv_query_xl and implicitly from json_query by naming the CSV format constraint.

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 source exclusivity ("one of the two": url or inline csv), explicit scope limits (one filter condition, no joins or aggregates), and a named alternative with its trigger condition and trade-off (over 5 MB → csv_query_xl, paid, 100 MB). The agent knows both when to use this and when to switch.

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

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

The description discloses extensive behavior beyond the readOnlyHint annotation: redirect limits, timeout, private-host rejection, non-2xx error behavior, truncation, absence of JavaScript execution, and the failure mode for SPAs or bot walls. It also explains the fix path for those failures, which is unusually helpful for an agent.

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

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

The description is dense but well structured and front-loaded: purpose first, then processing behavior, limits, failure modes, and alternatives. Every sentence carries actionable information, and the length is justified by the tool's complexity.

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

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

With no output schema and only a readOnlyHint annotation, the description carries the full burden and does so thoroughly. It explains the return format, truncation marker, error behavior, and the key limitations an agent must know before invoking the 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 all three parameters are already documented in the input schema. The description reinforces the maxChars truncation behavior and mentions headers for authentication, but it does not add much parameter semantics beyond what the schema already states.

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: fetch a public HTTP(S) URL and return its body as plain text. It also carefully distinguishes the output from siblings by naming fetch_html, fetch_metadata, html_to_markdown, and fetch_rendered with their respective use cases.

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 covers when to use this tool, when not to use it, and which alternatives to choose. It names the conditions that select fetch_html, fetch_metadata, html_to_markdown, fetch_rendered, screenshot_url, and authenticated headers.

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 readOnlyHint; the description carries the real behavioral burden: sanitization of scripts/styles/handlers, absence of JS execution with the SPA consequence, and truncation behavior at maxChars with a marker. These are non-obvious traits an agent needs before calling.

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 dense sentences, each loading information: safety/scope first, then the fetch_extract contrast, then the JS limitation, then truncation. No filler or restatement of the title.

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

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

No output schema exists, yet the description characterizes the return value precisely (tag/attribute-preserving HTML with listed elements stripped, truncated with a marker). For a 3-parameter tool with a nested headers object, 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. The description adds beyond the schema by noting that maxChars produces a cut with a visible marker, which tells the agent how truncation manifests in output rather than just that a cap exists.

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 ('fetch a page and return its HTML') plus an explicit statement of what is removed (scripts, styles, svg, iframes, comments, inline handlers) and what is preserved. It also names the sibling it is not (fetch_extract) so an agent can discriminate without opening a schema.

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

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

Explicitly routes the agent: 'For inspecting or rebuilding markup, not plain text (fetch_extract gives that).' It also gives a negative condition — no JavaScript, so SPAs return an empty shell — which tells the agent when not to use it.

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

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

Even though readOnlyHint is already set, the description adds substantial operational detail: 512 KB read cap, 5-redirect limit, 10 s timeout, private/local host rejection, non-2xx error behavior, and no JavaScript execution.

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 core purpose, then packs output shape, limits, security behavior, and alternatives into a dense but waste-free paragraph.

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 is present, yet the description fully specifies the JSON return shape, null/{} handling for missing fields, malformed jsonLd behavior, and error conditions, leaving nothing essential 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 both url and headers are already documented. The description reinforces the public/private URL rule but adds almost nothing about the headers parameter, so 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 — fetching a public URL's <head> metadata — and enumerates the returned fields, which clearly distinguishes it from fetch_extract and fetch_html.

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 excludes body-text use and names the two alternatives, fetch_extract for plain text and fetch_html for raw HTML, so the routing decision is unambiguous.

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; the description adds substantial behavior beyond that: which elements are discarded, truncation at maxChars with a visible marker, no JavaScript execution so SPAs return an empty shell, and table flattening. These are exactly the failure modes and output-shape facts an agent needs before calling.

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

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

Three dense sentences with zero throat-clearing. Safety and mutuality constraints are front-loaded, then output scope, then limitations – a sensible order for an agent scanning before invocation.

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

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

For a read-only converter with no output schema, the description supplies the return type ('text'), the truncation behavior, and the JS limitation that determines whether the tool is even viable for a given page. The empty-shell warning on SPAs is the kind of edge case that otherwise causes silent bad results.

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 baseline is 3. The description adds two things beyond the schema: it reiterates the url/html mutual exclusivity as a top-level constraint, and it reveals that maxChars truncation is signaled by an inserted marker, which the schema does not say. It says nothing extra about headers.

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

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

The description opens with a specific verb and resource ('Convert ... to Markdown') and then enumerates the exact conversion scope: headings, links, lists, emphasis, code, quotes. It distinguishes itself from the sibling fetch tools by framing both a URL-fetch path and a raw-HTML path, and from fetch_extract by naming what gets stripped.

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

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

It gives clear context for when this applies: post-processing a fetched page or converting a string you already have ('one of the two'). It cues the workflow with 'a fetched URL' and the stripped-element list, but never names fetch_html explicitly as the upstream sibling or states when to prefer it over fetch_extract.

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 the description adds real value beyond that: free tier, an explicit 5 MB cap with the failure mode ('errors on invalid JSON or over 5 MB'), and the non-obvious return shape (one match bare, several as an array). Those are exactly the traits 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?

All the critical facts come first — free, read-only, source exclusivity, return shape — in one tight paragraph with no filler. The density borders on cryptic in the syntax list, but nothing 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?

There is no output schema, so the description must carry return semantics, and it does partially (match cardinality, error conditions, limit-truncation guidance lives in the schema). A brief note on the error payload shape would close the remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the filter operators and the limit envelope. The description's main additions are negative constraints ('no slices or jq') and the 5 MB bound, which are useful but largely restate schema-level facts, so the baseline of 3 is right.

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 (JSONPath query over JSON from a URL or inline string) and pins the exact syntax subset supported. It also distinguishes itself from the paid sibling json_query_xl, so an agent can place it without opening a schema.

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

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

Explicitly notes url and json are mutually exclusive ('one of the two') and names json_query_xl with its 25 MB ceiling as the alternative for larger payloads. It stops short of routing against other siblings (csv_query, fetch_extract), so it is clear but not exhaustive.

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, so the description adds substantial context: cost per call, required payment payload, and the structured 402 response. It prevents the agent from misclassifying a normal payment challenge as an error.

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

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

Three compact sentences with the purpose, cost, and payment behavior front-loaded. Every sentence carries operational value with no filler.

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

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

For a tool with no output schema, the description identifies the returned metrics and explains the payment flow, which is the main complexity. It could say more about response shape, but the key behavioral information is present.

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 explains all four parameters. The description reinforces the 1-20 keyword constraint but adds no extra semantics for language_code, location_code, or include_suggestions.

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 data source and metrics (Google Ads volume/CPC/competition) and the exact input scope (1-20 keywords). This is more precise than a generic 'keyword research' label and makes the tool's output obvious.

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

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

It clearly states the paid nature and that a 402 response without a payment payload is expected behavior, which is critical invocation guidance. It does not explicitly compare against sibling tools, but none of the listed siblings are close alternatives.

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=false, and the description reinforces this with 'Free, read-only' and 'This tool saves nothing.' It also discloses the human-approval requirement before persisting anything, which annotations cannot express.

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 tight sentences: cost/safety first, then what it returns, then usage guidance. Every clause carries a decision-relevant fact, with nothing 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?

With no output schema, the description correctly summarizes the return value ('static text' with a note and save instructions) and covers the side-effect and approval model. Nothing needed to 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?

Schema coverage is 100% and the single 'harness' parameter is fully documented in the schema, including enum values. The description never mentions the harness parameter or why one would omit it, so it adds no meaning 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 and resource: returns static text containing a note on when ToolSnap tools fit and how to save it in the runtime's memory. This is clearly distinguishable from siblings like tool_catalog, use_tool, and task_recipes, which do other things.

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 it ('only if your user asks about persistent memory or ToolSnap setup') and adds the operating instructions: show the user the text, save only with approval. 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; the description adds the constraints that actually shape a call — 20 MB URL / 5 MB base64 caps, mutual exclusivity of the two inputs, truncation at maxChars with a marker, no OCR, no layout/table preservation, and the HTML-mislabeled-URL failure mode.

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 safety and scope, then inputs, then return behavior, then failure modes. No filler and nothing repeated from 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?

Covers what the tool returns (text, cut at maxChars with a marker) despite there being no output schema, and documents every behavioral risk of a 4-parameter extraction tool: size ceilings, input exclusivity, missing OCR, and non-preserved layout.

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 already 100%, so the baseline is 3; the description earns extra by adding size limits per input mode and confirming the url/data either-or that the schema only hints at, plus the truncation behavior tied to maxChars.

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 plain text from a PDF — plus the two accepted input forms. The 'PDF' scope cleanly separates it from fetch_html, html_to_markdown and fetch_extract even though no sibling is named.

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?

Makes the applicable domain explicit ('Text-layer PDFs only: scans return little or nothing'), which tells the agent when not to call it, and 'Fails if the URL serves HTML, not a PDF' routes HTML content elsewhere. No sibling is named outright, so the routing is inferred rather than stated.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses that invocation is free ('calling it charges nothing'), that prices can be exact or a default-args quote depending on the tool (fal.ai media), and what payment mechanics exist (x402 USDC on Base, minimum deposit, prepaid discount, SpendAuthorization). These are non-obvious traits an agent needs before relying on the numbers.

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 cost/read-only constraint, then routing guidance, then return shape, then the boundary against tool_catalog — a logical order. The return-value enumeration is dense and long, but it substitutes for the missing output schema, so most of it 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?

With no output schema, the description carries the burden of describing return values and does so concretely (menu fields, tools[] with tier, price_usdc, first_call_free, value note). It also notes the precision caveat for quoted prices, so an agent knows how much to trust the numbers.

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?

Zero parameters, so the baseline is 4; the description reinforces this with 'no arguments,' matching the empty schema. Nothing further is needed or claimed.

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 (pricing/payment options), its cost profile ('Free, read-only, no network, no arguments'), and precisely what it returns (a JSON menu of tiers and prices). It explicitly distinguishes itself from the sibling tool_catalog by scope: 'this one is only about cost.'

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: 'Call it before a paid tool to see its exact cost and whether first_call_free applies, or to choose pay-per-call vs prepaid.' It also routes the agent away to the correct alternative for a different need: use tool_catalog for descriptions and schemas.

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 say readOnlyHint=false and destructiveHint=false, which conveys little about a paid, non-mutating compute call. The description adds the price ($0.03 USDC/call) and pre-empts the most likely failure misread: a 402 without a payment payload is documented behavior, not an error. That is exactly the kind of 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?

Three short sentences, front-loaded with the capability and result, then cost, then the payment caveat. No filler and nothing 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?

For a one-parameter tool with no output schema, the description covers purpose, return value, cost, and the expected 402 path. An agent has everything needed to call it and interpret both success and the unpaid response.

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?

Single required parameter with 100% schema description coverage ('Public image URL'), so the schema does the work. The description adds only that the output is a transparent PNG URL, not anything about the input beyond what the schema states.

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 ('Remove an image's background') and even the output ('transparent PNG URL'). No sibling tool in the catalog does image manipulation, so the description alone is enough to distinguish it.

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

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

The payment clause effectively tells the agent how to invoke it correctly: without a payment payload you get a 402 rather than a result. There is no explicit when-not guidance or named alternative, but none of the sibling tools overlaps with this capability.

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 annotation: discloses truncation semantics ('Items past maxItems are dropped and truncated=true'), HTML stripping in descriptions, error conditions (non-2xx, 10 s timeout, private hosts refused), and the non-feed case. Cost ('Free') and safety profile are both stated.

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 capability and exclusion, and every clause carries a distinct fact. The telegraphic, fact-stacked style (comma-separated field lists, error list in one sentence) is efficient but dense enough to be slightly harder to scan than a cleanly segmented version.

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 fully compensates by enumerating the response envelope and item fields, plus the truncation flag. With only two parameters and full schema coverage, 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 baseline is 3; the description adds meaning by explaining that dropping items past maxItems sets truncated=true while itemCount still reflects the full total, clarifying the interaction between the two parameters. URL constraints (private hosts refused) are also reinforced in prose, though no format examples are given.

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 ('Fetch an RSS 2.0 or Atom feed and return JSON') and immediately enumerates the returned fields. It explicitly excludes JSON Feed and implicitly differentiates itself from siblings like sitemap_parse and fetch_metadata by naming its format scope.

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

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

Clearly positions when the tool applies (RSS 2.0 / Atom URLs) and adds an exclusion ('Not JSON Feed') plus a fallback behavior for non-feed URLs ('returns type unknown and no items'). It does not name an alternative sibling to use for JSON Feed or generic HTML, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations by disclosing per-call cost ($0.04) and explicitly framing the 402 payment-required response as expected behavior rather than an error — a real trap for an agent. It stops short of describing rate limits, timeouts, or what the image URL looks like/expires.

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

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

One compact line with the core action front-loaded, followed by cost and the non-failure 402 semantics in priority order. No wasted sentences.

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

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

Covers the essentials an agent needs for a 6-param, no-output-schema tool: what comes back (a public image URL) and how billing/payment surfaces. Parameter details are fully handled by the schema, leaving only minor gaps like URL lifetime and error conditions other than 402.

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 width, height, format, quality, and fullPage are already documented with defaults and constraints. The description adds no parameter meaning 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?

"Screenshot a page → public image URL" names a specific verb, resource, and the shape of the output, which cleanly separates it from the fetch_* and conversion siblings. An agent knows exactly what it gets back 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?

The description clarifies the paid call model and what a 402 response means, which is genuinely useful usage context. It does not say when to prefer this over fetch_html or other rendering tools, so the alternative-selection guidance is only implied.

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

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

Beyond readOnlyHint=true, it discloses the free/read-only nature, the exact failure modes (non-2xx, 10 s timeout, private hosts), the truncation flag, and that index children are not auto-fetched. That is a genuinely rich behavioral profile for a fetch 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?

Four short sentences, each doing distinct work: purpose, urlset return shape, index return shape, and failure constraints. Scoping and the 'call again per child' caveat are front-loaded where an agent will see them.

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 contract for both response variants (urls[], urlCount, truncated, sitemaps[]), plus operational limits. An agent has everything needed to decide, call, and interpret results without further probing.

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 url format and maxUrls default/cap/full-count semantics are already documented in structured data. The description adds little parameter-specific information beyond reiterating the uncompressed-URL constraint, 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?

"Fetch one XML sitemap and return JSON" gives a precise verb, resource, input format and output format. The follow-up sentences distinguish the two sitemap shapes (urlset vs sitemapindex), which an agent could otherwise conflate with the sibling rss_parse or generic fetch 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?

States clear boundaries: uncompressed XML only, no .gz, private hosts and non-2xx fail, and children of an index must be fetched with separate calls. It stops short of naming an alternative tool (e.g. rss_parse or fetch_extract) for non-sitemap feeds, so a sibling comparison is implied rather than explicit.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the main behavioral burden is covered. The description adds useful non-schema context: the tool is free, it returns workflow prompts, and omitting arguments produces a menu rather than an error.

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 three compact fragments, front-loaded with cost and purpose, then invocation behavior. Every part carries useful information with no waste.

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

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

For a simple, zero-required-parameter tool with full schema coverage and annotations, the description is nearly complete. It still does not explain what the menu contains or the shape of the returned prompt, but those are modest gaps given the tool's simplicity.

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 sole parameter is already documented. The description restates the omit-for-menu behavior and adds that a recipe id yields a prompt, but it does not add syntax, ID format, or discovery detail beyond the schema.

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

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

The description states a specific resource — "Multi-tool workflow prompts" — and gives concrete examples ("clone a site, SEO audit"), so its purpose is clear beyond the title. It is not fully explicit about how it differs from sibling tools such as tool_catalog, but the recipe/prompt framing is distinct enough for selection.

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 explicit call patterns: "No args → menu" and "recipe='<id>' → prompt." This is clear invocation context, though it does not name alternatives or say when to prefer this over a sibling 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 already declare readOnlyHint=true and openWorldHint=false, yet the description still adds real context: 'Free', 'no network', the precedence resolution order, and that unknown ids error while naming valid families. It does not, however, discuss whether catalog contents are static or change over time.

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 safety/scope facts, then walks the three call modes in the order an agent would try them. Telegraphic clauses carry high information density with no filler sentences.

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

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

There is no output schema, and the description compensates by enumerating the returned fields for each of the three modes, plus error behavior and the handoff to use_tool. Nothing needed 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 would be 3, but the description goes further by spelling out what each parameter mode returns (families with id/label/one-liner/count; tools with name/price/description/notes/inputSchema) and by stating the precedence between tool and family.

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

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

States a specific verb and resource (browse the tool catalog) plus concrete scope: 47 tools across 10 named families. The final sentence ('Run what you find via use_tool') separates it from the sibling that actually executes tools, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit mode selection: no args for the family index, family='<id>' for tools with schemas, tool='<name>' for a single entry, plus the precedence rule 'wins over family'. It also names the alternative tool for execution and states the failure mode for unknown ids.

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: it justifies readOnlyHint=false (inner tools may create a render, a stored file or a ledger entry) and destructiveHint=false (no catalog tool deletes or overwrites), and adds that pricing and payment apply verbatim, that errors propagate from the inner tool, and that unknown names fail with a pointer to tool_catalog. That is exactly the extra context annotations cannot carry for an aggregator whose safety profile is a catalog-wide worst case.

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 one-line purpose before the hint rationale, and every sentence carries information. It runs dense — the second sentence packs annotations, rationale, prerequisites and the self-call exclusion — which trades a little readability for completeness, but there is no filler to cut.

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

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

For a pass-through dispatcher with two params, full schema coverage and no output schema, the description covers everything an agent needs: how to resolve the inner tool, how args are forwarded, what safety posture to assume and why, and how failures behave. No gap remains that would cause a misinvocation.

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 both parameters are already documented in the schema, which sets the baseline at 3. The description does add real meaning — args pass through unchanged to the inner tool's inputSchema, and name must be an exact catalog name rather than 'use_tool' — but it is confirming and constraining what the schema says rather than introducing new parameter behavior.

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 — runs any catalog tool that is missing from tools/list — and frames it as exactly equivalent to a direct call, with args, price, payment, result and errors passing through verbatim. This clearly separates it from the sibling tool_catalog (discovery) and from every concrete tool (no wrapper needed).

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 precondition (the tool is missing from your tools/list), a required preceding step (fetch name, schema and annotations via tool_catalog(tool='<name>')), an explicit exclusion (it cannot call itself), and the failure mode (missing or unknown name errors pointing to tool_catalog). Nothing about when to reach for this versus the alternatives 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.