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

Annotations cover safety (readOnly/openWorld/non-destructive), but the description adds substantial operational context the annotations do not: up to five engines selected, automatic time-window inference from phrases like 'this week', a cap of 10 results, and a concrete cost of 5 credits. Cost and result-cap disclosure is exactly the kind of trait an agent needs for budget-aware selection.

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, front-loaded with the trigger condition, then capability and cost, then the routing alternative. No filler and nothing repeated.

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 no explanation, yet the description still usefully bounds the result count. For a single-parameter discovery tool, the trigger condition, alternatives, cost, and result cap together make it fully sufficient to call correctly.

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

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

Schema coverage is 100% and already documents the query parameter, including platform and time hints. The description reinforces the time-hint inference mechanism ('infers a time window from phrases such as "this week"'), adding a little meaning beyond the schema, though most detail is duplicative of the schema text.

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

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

States a concrete verb and resource ('describe what you are looking for in natural language') and frames the scope as cross-source discovery. It explicitly contrasts with the sibling 'search' by naming the condition that separates them, so an agent can distinguish the two without opening schemas.

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

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

Gives an explicit when-to-use ('when you do not know which source to search') and an explicit alternative with its own condition ('use search when you already know the engine'). Both sides of the routing decision are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and open-web profile is covered structurally. The description adds that the output is extracted readable text rather than raw markup, plus the public-URL restriction, but says nothing about failure modes (paywalls, JS-rendered content, rate limits).

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

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

A single sentence with zero padding; the action and output are front-loaded and the input-sourcing hint is appended without derailing the sentence.

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 needn't explain return values, and the single input is fully documented. It is nearly complete for a one-parameter read tool, with the main gap being no guidance on unreadable or dynamically rendered pages.

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

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

Only one parameter, and the schema already describes it fully (format: uri, 'Public HTTP or HTTPS URL to retrieve') at 100% coverage, so the baseline is 3. The description reinforces the public-URL constraint and hints at the URL source, but adds no format or validity 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?

States a specific verb (extract) and concrete outputs (readable title and full text) from a clearly bounded resource (a public URL). It does not explicitly distinguish itself from siblings like render_results or sitemap, which an agent might plausibly confuse with page retrieval.

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?

'Supplied by the user or returned by search' implies a usage chain after the search tool, which is useful contextual guidance. However, there is no explicit when-not guidance or mention of when a sibling such as render_results (e.g., JS-heavy pages) would be the better choice.

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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds that results are "citable" with title/URL/snippet/optional text, but says nothing about cost, freshness guarantees, or rate behavior beyond what the schema's credit note already implies.

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

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

Two sentences, purpose front-loaded and trigger condition second, with zero filler. Every clause 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 a rich schema, output schema, and safety annotations, the description covers enough to call the tool. The notable gap is sibling routing: in a toolset containing both `search` and `trending`, the description never explains why an agent should pick `news` over those alternatives.

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 fully documents all seven parameters (including the credit cost of crawl_results and the recency enum). The description adds no parameter-level meaning, 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 ("Search current news") plus the triggering user intent, so the agent knows this is a news-retrieval tool rather than a general one. However, it never distinguishes itself from the sibling `search` or `trending` tools, leaving ambiguity about which to pick.

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?

"when the user asks about recent events, announcements, or coverage" gives clear, actionable context for when to invoke this tool. There are no exclusions or named alternatives (e.g. no guidance on choosing `trending` for trending topics over `news`), so it stops short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new traits beyond them: graceful degradation when the host has no UI support, a hard prohibition on inventing URLs or factual titles, and the note that this does not consume search credits. These are behavioral facts an agent could not derive from the annotations or schema.

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

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

Four tight sentences that are front-loaded: capability and fallback first, then when to use, then input constraints, then explicit non-capabilities. No sentence is redundant with structured fields, and each adds a distinct constraint.

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 no prose explanation. The description still covers everything an agent needs to invoke it correctly: caller prerequisites, ordering intent, host-capability fallback, and the boundary against adjacent research tools. Nothing material is missing for a 2-parameter, non-mutating render 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 the schema already documents title, results, id, url, text, and metadata – this sets the baseline at 3. The description adds ordering semantics ('Pass existing results in the desired order') and reinforces that the payload must be pre-existing rather than newly fetched, which is meaningful beyond the field-level docs.

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 – present already-retrieved results as source cards with a text-list fallback – and immediately bounds the scope with negations ('Does not search, crawl, fetch URLs, verify sources, or consume search credits'). This cleanly separates it from siblings like search, crawl, and sitemap, which is exactly the confusion an agent would otherwise face.

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

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

Gives an explicit trigger ('when the user wants to browse sources or a visual list helps the task'), an explicit anti-trigger ('Do not call for intermediate research results or when a text answer is sufficient'), and enumerates the excluded operations. There is also a prerequisite: results must already exist. Nothing about when to select this tool is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the result shape (id, title, URL, text) and the read-in-full affordance, but that overlaps with the existing output schema and omits operational context such as the per-crawl credit cost that the schema notes. Additive value beyond structured fields is modest.

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 purpose before the return details. Tight overall, though the final sentence ('Each result includes a URL that can be read in full') is largely redundant with the preceding description of result fields.

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

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

For an 8-parameter tool with full schema coverage, an output schema, and rich annotations, the description delivers a clear purpose and return summary. Guidance on engine selection tradeoffs is left to the schema, which is acceptable given the structured fields cover it.

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 8 parameters — including the pagination caveat for specific engines and the credit cost of crawl_results — are already documented in the schema. The description adds no parameter-level meaning, 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 ('Search the live public web') and the information need it serves ('current information, sources, or research'), clearly distinguishing it from a plain lookup. It does not explicitly name siblings like news, trending, or crawl, so an agent must infer the boundary between general search and those specialized 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 a clear use context — when the user needs current information, sources, or research — which is exactly the trigger condition for a search tool. It stops short of naming alternatives (news, trending, crawl) or stating when-not to use it, but the positive guidance 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 already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds that only public links are surfaced, but says nothing about crawl depth, result limits, or how discovery is scoped — modest added context over the annotations.

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

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

A single front-loaded sentence combining the action with the trigger condition; no filler. Slight redundancy between 'related public links' and 'available pages' keeps it from being maximally tight.

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

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

For a one-parameter read-only tool with an output schema and rich annotations, the description supplies the needed intent and scope. Return values need not be explained since an output schema exists; the only gap is disambiguation from the crawl sibling.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents 'url'. The description's 'page or domain' phrasing reinforces that a domain is acceptable, but adds no format or constraint detail 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 (discover) and resource (related public links from a page or domain), and scopes it to public links. It does not explicitly differentiate itself from the sibling 'crawl', which also traverses sites, so an agent must infer the boundary.

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

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

Gives a clear selection context: use when the user wants to explore a site's structure or available pages. It stops short of naming the closest alternative (crawl) or stating when not to use it, leaving the sitemap-vs-crawl choice to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety and reach profile is fully covered structurally. The description adds the scope 'currently trending' but nothing about rate limits, auth, or freshness/pagination behavior beyond what the annotations supply.

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

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

A single sentence that front-loads the action and payload, then appends the usage trigger. Nothing is wasted, though it is slightly dense and could separate the 'what' from the 'when' more cleanly.

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, rich annotations, and full schema description coverage, the description only needs to establish purpose and invocation context, which it does. The one unmentioned detail, that github is the default service, is already carried by the schema.

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

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

Schema description coverage is 100%, so both search_service and max_results are already documented in the schema, and the description's mention of GitHub/Hacker News merely echoes the enum. It adds no format, default, or range guidance, 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 (List) and resource (currently trending repositories or stories) with the source platforms named, so an agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling 'news' or 'search' tools, which is the only thing keeping it out of the top band.

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

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

The clause 'when the user asks what is popular now' gives clear triggering context and is embedded directly in the description rather than left implicit. There is no exclusion or named alternative, but the invocation condition is unambiguous.

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