Deezer

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds behavioral details: default model is free, Anthropic requires BYO key, return format includes per-model score/confidence/signals/raw_response, and combined view. No contradictions with annotations.

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

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

Three concise sentences front-loading the main purpose, with no fluff. Every sentence adds essential information (what it does, how to use, return structure, use cases).

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?

Despite no output schema, the description adequately explains the return format and key behaviors (default model, key usage). Minor gaps: no mention of error handling or unsupported model behavior, but overall complete for a tool of this complexity.

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?

With 100% schema description coverage, baseline is 3. The description adds value by clarifying default model behavior, that '_apiKey' is passed directly to Anthropic, and that 'context' disambiguates common names. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool probes LLMs for brand/product visibility, scores 0-100 per model, and specifies default model and optional Anthropic. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on scoring visibility across multiple LLMs.

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 explicitly lists use cases like AI-marketing audits and pre-launch checks, and explains when to use '_apiKey'. However, it does not contrast with similar sibling tools (e.g., 'scan_competitor_ai_presence'), leaving some ambiguity about when to prefer this 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 indicate read-only, idempotent, non-destructive behavior. The description adds the return content (metadata + tracklist) but doesn't disclose additional traits beyond 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?

Extremely concise, one sentence front-loading the core purpose. No extraneous words.

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 retrieval tool with an output schema, the description is adequate. It could include more context, but the presence of an output schema mitigates the need for return value details.

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 'id' parameter, but the description explicitly mentions 'by Deezer album id', adding meaningful context beyond the schema's type-only definition.

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

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

The description clearly states that the tool retrieves album metadata and tracklist using a Deezer album ID. It specifies the resource and method, distinguishing it from sibling tools like 'artist' or 'track'.

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

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

No guidance on when to use this tool versus alternatives. With many sibling tools (e.g., artist, track), an agent lacks context for tool selection.

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

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

The description adds minimal context (use of Deezer ID) beyond annotations, which already declare it read-only, idempotent, and non-destructive. It does not reveal additional behavioral traits.

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?

Single sentence with no wasted words; perfectly concise for the information conveyed.

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 is sufficient for a simple lookup, though it could hint at the returned fields (e.g., name, picture) for completeness.

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?

With 0% schema coverage, the description clarifies the single parameter's meaning ('by Deezer artist id'), compensating well but could specify format or source more precisely.

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

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

The description clearly states the tool retrieves artist metadata using a Deezer artist ID, with a specific verb ('by') and resource ('metadata'), effectively distinguishing it from siblings like 'artist_top'.

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

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

No guidance on when to use this tool versus alternatives like 'entity_profile' or 'artist_top'; the description lacks context for selection.

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 destructiveHint=false, so the safety profile is known. The description adds behavioral context by detailing the output fields (track id, title, rank, duration, album, 30-second preview URL) and the limit of up to 100 tracks, which is useful beyond 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?

The description is three concise sentences with no irrelevant content. The first sentence states the core function, the second details the output fields, and the third reinforces the purpose. Every sentence 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?

Given the tool has an output schema and annotations covering safety, the description provides sufficient context: it identifies the input (artist id, optional limit), the output fields, and the intended use case. It is complete for a simple read-only lookup 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?

The input schema describes only the limit parameter (1-100, default 25), not the id. The description clarifies that id is a Deezer artist id and that results are limited to up to 100, partially compensating for the missing id description. This adds meaning 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 uses a specific verb ('returns') and clearly identifies the resource: 'the most-streamed tracks for one Deezer artist id, up to 100.' It also explicitly states the purpose: 'Answers what an artist's biggest songs are on Deezer.' This distinguishes it from sibling tools like artist or track.

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

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

The description provides a clear usage context by stating the tool answers what an artist's biggest songs are, implying it should be used for artist top tracks. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full 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 mark it read-only, idempotent, and non-destructive; the description adds useful behavioral context about routing, automatic argument filling, and stable pipeworx:// citation URIs. It does not cover latency, failure modes, or limitations, but the added routing/citation context earns a 4.

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 intended description is front-loaded and well organized (priority, trigger phrases, examples), but the provided text degenerates into a long repeated fragment ('even if web search could also answer it... START HERE for most questions') that adds no value and harms navigation. This fails the 'every sentence earns its place' test.

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 natural-language tool with safety covered by annotations, the description is largely complete: it states the domain coverage, trigger phrases, examples, routing mechanism, and citation-bearing return format. It lacks explicit guidance on when to pick ask_pipeworx_beta/grounded or search/deep_research instead, but 'START HERE for most questions' provides a usable default.

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

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

Schema coverage is 100%, so the schema already documents the single required question parameter and aliases. The description adds natural-language examples and says the tool 'fills arguments', but it does not materially expand parameter semantics beyond what the schema provides; baseline 3 is appropriate.

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

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

The opening sentences clearly define the tool as a router that sends natural-language questions to 5,798 tools across 1,517 sources and returns cited structured answers. It is distinguishable from general web search, though it does not explicitly differentiate itself from sibling ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of a 5.

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

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

The description gives strong when-to-use guidance: prefer over web search for factual/current/historical questions, use whenever the user asks 'what is', 'look up', 'get the latest', etc., and start here for most questions. It provides examples but no explicit when-not-to-use or named alternatives among sibling tools.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description discloses that candidate routing improvements may be enabled live, that no candidate is currently active as of a specific date, and that this is a full working router rather than a fallback. This is valuable behavioral context for an experimental tool.

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

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

The description is information-dense without being bloated. It front-loads the core identity, then explains the current state, usage guidance, and the absence of a fallback, with each sentence earning 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?

The description is complete for an experimental routing tool: it covers identity, behavior relative to the stable version, current status, usage direction, and response parity. The absence of an output schema is mitigated by the explicit statement that the response shape matches ask_pipeworx.

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

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

Schema coverage is 100%, with the question parameter and all aliases already documented. The description only says 'same arguments' as ask_pipeworx, which reinforces parity but does not add meaningful parameter semantics beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly differentiates from the stable ask_pipeworx by noting candidate routing improvements and its experimental edge, so an agent can distinguish it from siblings.

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

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

It explicitly says to use it like ask_pipeworx when wanting the newest routing, and it names the stable router as the comparison baseline. It does not provide an explicit 'when not to use' statement, but the experimental-versus-stable distinction makes the intended usage clear.

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

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

Beyond the annotations, the description discloses the refusal behavior, exact refusal reasons, return shape including evidence and fetched_at, and the extra LLM call cost. It also clarifies that answers are grounded only in the tool result, adding meaningful context the annotations do not provide.

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 front-loaded with the core purpose and then delivers actionable details about output, refusal, and when to use it. It is dense but each clause contributes useful guidance, though it could be tightened slightly without losing 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?

The tool has no output schema, so the description compensates by specifying the success and refusal response shapes. It also covers routing, when to prefer the alternative, cost implications, and the grounding guarantee, making it complete for correct invocation.

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

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

Schema coverage is 100%, and all parameters are documented aliases for the natural-language question. The description does not add parameter-level detail beyond that, but it is not required to because the schema fully specifies the input contract.

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 identifies a specific verb and resource: an answer mode that extracts answers only from tool results, returning evidence and confidence. It explicitly differentiates from the sibling ask_pipeworx by noting the same routing but grounded extraction behavior.

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 states exactly when to use the tool: when answers will be quoted, cited, or acted on in high-stakes contexts, and when not to: prefer ask_pipeworx for casual lookups. It also names the alternative and the cost tradeoff, leaving no ambiguity.

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

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

Annotations already mark this as readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: resolution confidence levels, parent event extraction, news fallback mechanisms, safety checks for low-confidence matches, handling of closed markets, wide-spread warnings, and cancellation rule analysis. This goes well beyond what annotations provide.

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 thorough but very long, covering many edge cases and details. While this is appropriate for a complex tool, it lacks conciseness and could benefit from a more structured format (e.g., bullet points or sections).

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 tool's complexity (multiple classifiers, fan-out examples, response shapes, resolver contract, parent event extractor, news fallback, safety rules, and cancellation risk), the description is remarkably complete. It addresses many scenarios and provides actionable guidance, compensating for the lack of output 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%, and the description adds only minor clarification (e.g., market can be slug, URL, or question). The baseline is 3, and the description does not significantly enhance understanding 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 uses a specific verb ('Research') and identifies the resource (Polymarket bet via Pipeworx data). It explains what the tool does in detail, including inputs and outputs. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, which share a focus on Polymarket bets.

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 explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and examples but does not specify when NOT to use it or mention alternatives by name.

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, idempotentHint, and not destructive. The description adds 'Current chart' implying recent data, but doesn't go beyond annotations. No contradictions.

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, no superfluous words, front-loaded with key purpose. Highly efficient.

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 tool's simplicity, annotations cover safety, and output schema exists, the description adequately covers purpose and parameter usage. Missing details about genre_id range or return format, but output schema presumably handles that.

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 has 100% coverage with description 'Default 0 (all genres).' The description adds context that 0 means worldwide, which is helpful but only marginally extends the schema's information.

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?

Clearly states it returns the current chart of top tracks/albums/artists, distinguishing from siblings like album, artist, track which focus on individual entities. However, it doesn't specify whether all three categories are returned in one chart or separately.

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 a usage hint ('Pass genre_id 0 for worldwide') but does not explicitly state when to use this tool versus alternatives like artist or track tools. No guidance on 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?

Beyond annotations (readOnly, openWorld, idempotent), description adds specific behavioral details: pulls latest 10-K from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs. For drugs, specifies FAERS data sources.

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?

Description is front-loaded with example queries and concise. Each sentence adds value, though slightly lengthy. Structured logically with type-specific explanations.

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 no output schema, description adequately explains return format (paired data + citation URIs). Covers both entity types and edge cases like off-calendar fiscal years. Lacks details on data depth (e.g., number of years) but sufficient for comparison use case.

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%. Description adds meaningful context: explains values are tickers/CIKs for company, names for drug, with examples. Clarifies min/max items, which is implicit in schema but reinforced.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with multiple example queries. It distinguishes itself from siblings like entity_profile by explicitly saying it replaces sequential single-pack lookups.

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 guidance to prefer this tool over sequential lookups for comparisons. Gives example queries and explains coverage. Could be more explicit about when not to use or alternatives, but the context is clear.

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 idempotentHint=true. The description goes well beyond them: it discloses that findings are verbatim evidence with confidence/source/fetched_at and pipeworx:// citations, that gaps[] are explicit when data can't answer, that it never invents, and that thorough/standard include contradictions[]. It also discloses latency ranges and the paid requirement for thorough. No contradiction with 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?

Dense and front-loaded with the most operationally critical constraint (account required, paid tier for thorough) before the core capability. Every sentence adds value, though the sentence structure with parentheticals and semicolons makes it a bit heavy; it could be broken into cleaner sentences without losing content.

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

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

Despite no output schema, the description fully describes the return shape: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], contradictions[], and excerpting behavior. It also covers expected latency, prerequisites, and alternatives. An agent has everything it needs to decide and call 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 coverage is 100%, so the schema already describes both parameters. The description adds semantic value by explaining depth levels in plain terms (quick=3 single hop, standard=3 with gap recovery plus contradictions, thorough=6 paid with iterative hop), which enriches the enum semantics beyond the schema's wording. It could have also mapped depth to latency more explicitly, but it already mentions timing in the 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?

The description states a specific verb and resource: multi-source research over Pipeworx's 1517 structured data sources, explicitly contrasting itself with open-web search. It distinguishes itself from ask_pipeworx and mentions decomposition across 5,798 tools in parallel, so an agent can tell it apart from siblings.

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 (broad/multi-part questions over structured data) and when not to (single lookup -> ask_pipeworx; not signed in -> ask_pipeworx). It also names the alternative and the condition that selects it, plus tier/plan guidance. This is exceptionally actionable.

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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds valuable context: returns top-N tools with full schemas and examples, ready to call directly. No contradiction with 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?

Description is well-structured: front-loaded with purpose, followed by domain list, then return details and usage note. Every sentence adds value without 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?

Given no output schema, description thoroughly explains return format (top-N tools with schemas and examples) and usage context. Covers purpose, when to use, and behavioral expectations completely.

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 covers 100% of parameters with descriptions. Description does not add new parameter details but provides concrete examples (e.g., 'look up FDA drug approvals') that clarify usage, slightly exceeding the baseline of 3.

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?

Description clearly states 'Find tools by describing the data or task' and lists specific domains, distinguishing it from sibling tools like 'search' which query data. It explicitly positions itself as a first step for tool discovery.

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 indicates when to use: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear when-not guidance by contrasting with direct answer tools.

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

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

Annotations already mark it read-only/idempotent, but the description adds substantial behavioral context: parallel fan-out across sources, USPTO soft-fail behavior, empty FDA sections being expected, private-company resolved:false behavior, and sources_used/sources_failed semantics. No contradiction with annotations exists.

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 long but front-loaded with user examples and organized by output section, which suits the tool's complexity. Some parameter details duplicate the schema, but the overall structure makes the dense information navigable.

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 full burden of explaining results, and it does so thoroughly: it enumerates every result section, field details, failure modes, source behavior, and empty-data semantics. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the schema's ticker/CIK/name examples and the interchangeability of type values without adding meaningful new 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?

The description opens with a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call,' supported by concrete user-phrase examples. It clearly distinguishes this tool from chaining individual SEC/XBRL/news lookups and names the sections it returns.

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

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

It explicitly says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It does not, however, define boundaries relative to deep_research or compare_entities, so the exclusion guidance is incomplete.

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 provide destructiveHint=true and idempotentHint=true. The description adds that it deletes a previously stored memory, implying the key must exist, but does not elaborate on failure behavior or side effects.

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 concise sentences that front-load the action and purpose. No unnecessary words.

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 tool with one parameter, good annotations, and no output schema, the description covers what, when, and how sufficiently.

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

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

Schema coverage is 100% with a single parameter. The description does not add information beyond the schema's description for the 'key' 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?

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory by key). It distinguishes from sibling tools remember and recall.

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 contexts for use: stale context, task done, clearing sensitive data. Suggests pairing with remember and recall, but does not explicitly state 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?

The description adds significant behavioral detail beyond annotations: it explains the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This clarifies the read-only, idempotent nature implied by annotations and provides complete process transparency.

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

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

The description is concise, three sentences long, with the main action front-loaded. Every sentence adds value: first defines output, second explains process, third gives use cases. No wasted words.

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 no output schema, the description adequately describes the output as 'a single text blob ready to drop at site-root/llms.txt'. The tool is simple with 2 well-documented parameters, and the description covers input, process, output, and use cases completely.

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 repeats schema info (e.g., 'Full URL', 'Maximum number of link entries') without adding new semantics. No additional parameter context is provided beyond what the schema already conveys.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the process of fetching, extracting, and emitting markdown. It distinguishes itself from siblings by focusing on llms.txt generation rather than general AI visibility checks or other analyses.

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

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

The description provides three explicit use cases: getting client sites indexed, drafting for own projects, and auditing competitor visibility. While it doesn't explicitly exclude scenarios or compare to siblings, the examples give clear guidance on when to use the 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the return fields and that it lists active subscriptions (optionally inactive), which is consistent with annotations. No additional behavioral traits beyond what annotations indicate, so a score of 3 is appropriate.

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

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

The description is two short sentences: first states purpose and return fields, second gives usage guidance. No extraneous information; every sentence is essential.

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 tool's simplicity, comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint), 100% schema coverage, and explicit listing of return fields in the description, the description is complete for its purpose. No output schema is needed as fields are enumerated.

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 a single optional parameter 'include_inactive' clearly described. The description does not add further parameter details beyond the schema, 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?

The description states the specific verb 'List' and resource 'the caller's active subscriptions', and lists the fields returned (id, type, params, created_at, last_fired_at, fire_count). This clearly distinguishes it from siblings like subscribe and unsubscribe.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. This implies when to use it, though it doesn't mention when not to use it or explicitly name alternatives, but context from siblings provides sufficient differentiation.

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?

Despite annotations being minimal (readOnlyHint false), the description discloses key behaviors: filing returns a claim_token, passing it later reads status/changes, rate limit of 5/day, free, and does not count against quota. It also notes that the team reads digests daily, giving the agent a sense of impact and latency. No contradiction with 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 description is longer than a typical tool description but every section serves a clear purpose: definition, usage, exclusions, follow-up mechanism, and policy. It is front-loaded with the core purpose and then expands logically. A slight deduction for the almost-marketing sentence about roadmap influence, which is useful context but not strictly necessary.

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 feedback submission tool with 100% schema coverage and no output schema, the description fully covers what the agent needs: when to use, how to frame feedback, exclusions, token flow, rate limits, and quota impact. The lack of an output schema is mitigated by the description explaining the claim_token return and subsequent retrieval. No gaps remain.

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%, providing parameter descriptions for type, context, message, and claim_token. The description adds value by explaining the claim_token round-trip workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which is semantics beyond the schema's generic 'Read the reply...' text. Thus above baseline 3.

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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from all sibling tools, which are data retrieval or subscription tools. The subsequent bullet-like enumeration of feedback types (bug, feature/data_gap, praise) reinforces 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?

Explicit guidance is given: 'Use when a tool returns wrong/stale data,' 'when a tool you wish existed,' and 'when something worked surprisingly well.' It also provides an exclusions clause ('ONLY for tools served by this Pipeworx connection') and directs users to file elsewhere for non-Pipeworx tools. This is textbook when-to-use/when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable context: data source (CF analytics-engine), no PII, cached 5min-1h. This fully discloses behavioral traits without contradiction.

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

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

The description is brief yet comprehensive, with a front-loaded main result, three bullet-pointed use cases, and a technical note. Every sentence adds value, and the structure is clean.

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?

While the tool is simple with one parameter and no output schema, the description lacks explicit return format (e.g., JSON structure). However, it conveys the core output (top tools, packs, volume) and caching behavior, which is likely sufficient for an agent to use 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 repeats the schema's parameter description exactly, adding no new meaning. The context about shorter vs longer windows is already in the schema description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, using a specific verb and resource. It distinguishes from siblings by focusing on trending popularity derived from AI agent calls, which is unique among the listed 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?

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment of use case with agent needs. It provides clear context but does not explicitly exclude any scenarios or compare to alternatives, though the sibling list implicitly offers other options.

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 indicate read-only, open-world, idempotent, non-destructive. Description adds rich behavioral context: semantic anchor (Jaccard similarity ≥0.30), partition filter for placeholder slugs, fill check against CLOB depth, and conditions for actionable signals. No contradiction with 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?

Description is well-structured and front-loaded with purpose and mode selection. Every sentence adds value, though slightly verbose with detailed technical explanations (e.g., Jaccard similarity, partition filter). Could be trimmed while retaining clarity.

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?

Despite no output schema, the description thoroughly outlines the response structure (opportunities array, partition_check object, fill check results). Covers all modes, filtering mechanisms, and edge cases (placeholder slugs, low similarity). Complete for a complex arbitrage detection 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 100% for both parameters. Description greatly expands on schema by explaining modes, expected input formats (slugs or URLs, seed questions), and how each mode operates. This adds significant value beyond basic parameter descriptions.

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

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

The description states a specific verb ('Find arbitrage opportunities'), resource ('Polymarket'), and method ('monotonicity violations + partition-sum checks'). It clearly distinguishes three modes (no-args trending scan, event mode, topic mode) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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 when-to-use guidance: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode for a specific market. Also explains when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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 provides extensive behavioral detail beyond the annotations, including the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), how each calculates edge, response structure (by_segment, diagnostics), caching ('Cached 1h at the KV level'), and the 'TRADEABLE-EDGE KNOBS'. This adds significant context without contradicting 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 description is extremely verbose, containing dense technical details about model families, filters, and response fields. While thorough, it could be significantly trimmed for conciseness without losing essential meaning. The core purpose is front-loaded, but the length detracts from readability.

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 complexity (9 parameters, no output schema), the description is exceptionally complete. It covers response structure by segment, diagnostics, caching behavior, knobs, and even caveats (e.g., Fed markets). This level of detail ensures an agent can fully understand tool behavior without external documentation.

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

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

Schema coverage is 100%, so each parameter already has a description. The long description references some parameters (e.g., min_liquidity, max_spread_pp) but adds limited new semantics beyond what is in the schema. The baseline of 3 is appropriate as the description provides some interaction context but does not substantially enhance parameter understanding.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan'), resource ('Polymarket markets'), and outcome ('discover opportunities'), distinguishing it from siblings like polymarket_arbitrage by emphasizing edge detection from data disagreement.

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 explicitly frames the tool as 'built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' giving clear context for use. While it does not directly name alternatives or state when not to use, the context is strong enough to infer appropriate use cases, meriting a 4.

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

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

The description goes well beyond annotations (readOnlyHint, openWorldHint, destructibeHint=false) by detailing output structure (tracked, expired, snapshot_dates), explaining that snapshots are written on cache-miss, and clarifying that decay numbers are from daily closes, not intraday. No contradictions with 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 description is detailed but well-structured with a clear breakdown of output fields (tracked, expired, snapshot_dates) and a LIMITS section. While somewhat lengthy, every sentence adds value and is logically organized.

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 only 2 optional parameters, no output schema, and annotations present, the description is remarkably complete. It thoroughly explains the response format, edge_pp_net time-series, trend computation, expired opportunities with lifespan, and snapshot date gaps. It also covers limitations like TTL and snapshot activation time.

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 description adds valuable context: days default 14 with clamp 2-30 (schema says clamp 2-30, description says max 30), window default '1wk' and explanation of 'snapshot family'. This enriches the parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's function: edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question about edge duration and trend, distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description provides clear context on when to use the tool (for edge persistence analysis) and includes LIMITS section that explains constraints like 60-day snapshot TTL and snapshot availability. However, it does not explicitly state when not to use or name alternatives, though the context is sufficient for appropriate selection.

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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds context about walking the order book, returning verdicts, and explaining forced_directional_risk. No contradiction; description enhances annotation signals.

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 somewhat lengthy but well-structured with uppercase labels and bullet-like formatting. It front-loads the core purpose and clearly separates modes. Every sentence adds value, though some trimming could improve conciseness.

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

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

Despite no output schema, the description enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains key concepts like forced_directional_risk and thin_legs. It fully addresses the complexity of single-market and basket modes.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining how size_usd is interpreted differently in single-market vs basket mode, and how side defaults are determined. It provides necessary operational context.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, specifying both single-market and basket modes. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by describing its unique risk-assessment role.

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 states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the consequences of not using it (partial basket fills leading to unhedged directional positions).

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

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

The description goes far beyond the annotations: it discloses gross-vs-net fee treatment, compatibility_codes semantics, temporal alignment null meaning, skipped comparison categories, and that matching is keyword-based rather than source-verified. Annotations already declare readOnlyHint and idempotentHint, and the description aligns with those while adding substantial behavioral 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?

The description is long, but the complexity justifies most of the length. It is front-loaded with the core purpose, then organized into clear labeled sections (modes, response, safety fields, fees, skipped counters). A few phrases could be tightened, but it remains structured and each section 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?

There is no output schema, so the description carries the full burden of explaining return values. It covers prices, top_spreads_pp, compatibility fields, temporal_alignment, fees_note, skipped counters, and per-entry flags. It even explains the semantics of null temporal_alignment and the meaning of each compatibility code. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the mutually exclusive modes, the override behavior of kalshi_event_ticker and polymarket_event_slug over topic-mapped sides, and the exact shortcut values. It also clarifies that no parameters are required and how the tool behaves when both modes are used.

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 function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from the sibling polymarket_arbitrage and other Polymarket-only tools by naming both venues and the comparison outcome. The two modes are explicit and the purpose 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?

The description gives strong within-tool usage guidance: when to use `topic` shortcuts versus explicit ticker/slug pairings, and warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. It does not explicitly compare against sibling alternatives like polymarket_arbitrage, but the mode-selection guidance is clear enough for an agent to choose 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds valuable context about scoping (by identifier) and pairing with remember/forget. No contradiction.

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

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

Two sentences, front-loaded with core action, no wasted words. Efficient and clear.

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 simple tool (1 optional param, no output schema, rich annotations), description covers scoping, usage, and pairing with siblings. Complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with one parameter described. Description adds 'omit to list all keys', which clarifies the optional parameter's behavior beyond the schema's description.

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?

Clearly states two operations: retrieve a specific value by key, or list all keys by omitting the argument. Specifies the verb 'retrieve' and resource 'value saved via remember'. Distinguishes from siblings by naming 'remember' and 'forget'.

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: to look up context stored earlier without re-deriving. Implicitly pairs with remember/forget. Does not explicitly state when not to use, but context is clear.

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 describes a mutation (mark_read:true flags events as read) while annotations declare readOnlyHint=true. This is a direct contradiction, as the tool modifies state via mark_read. The description adds other behavioral details (return payload structure) but the contradiction severely undermines transparency.

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

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

The description is concise (three sentences) and front-loaded with the main action. Every sentence adds value, and there is no wasted text. The structure is efficient and easy to parse.

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

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

The description explains what returned events contain (source, citation_uri, payload) and mentions mark_read behavior. It covers filtering and polling. However, it omits mention of the 'limit' and 'unread_only' parameters, though they are in the schema. With 5 parameters and no output schema, some missing context is acceptable but not fully complete.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by giving examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explaining the effect of mark_read on subsequent calls, which goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource ('fired events') and the action ('pull'). It distinguishes itself from siblings like 'list_subscriptions' by focusing on alerts/events rather than subscription management.

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

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

The description provides context about usage (polling works fine, alternative endpoint) but does not explicitly state when not to use this tool or compare it to siblings like 'list_subscriptions' or 'recent_changes'. However, the clarity of its purpose implies appropriate use cases.

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?

Discloses internal fan-out to multiple sources (SEC, GDELT→GNews fallback, USPTO), explains failure modes (API sunset, rate limits), and describes return structure. This goes beyond the annotations which already indicate read-only, idempotent, and open-world characteristics.

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 well-structured: front-loaded with typical queries, then explains sources and behavior, then parameter details. Every sentence adds substantive information without redundancy. Length is appropriate for 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?

Given the tool's complexity (multiple sources, fallback logic, output format), the description is thorough. It describes return structure (changes grouped by source, total_changes, pipeworx:// URIs) even without an output schema. It also references a sibling tool for static data.

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?

While schema covers parameters with descriptions, the description adds valuable context: explains relative date shorthands (7d, 30d, 3m, 1y), recommends '30d' or '1m' for monitoring, and clarifies value accepts ticker or CIK. Schema coverage is 100% but description still enhances understanding.

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

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

The description clearly states the tool retrieves a change feed for a company over a time window, using specific verbs and examples. It distinguishes from the sibling tool 'entity_profile' by contrasting dynamic vs. static profiles.

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 when-to-use and when-not-to-use guidance, including a direct alternative ('Use entity_profile instead'). It also gives example queries and a recommended default for 'since'.

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

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

The description adds significant behavioral context beyond annotations: key-value store scoped by identifier, persistence duration (24 hours for anonymous), and idempotent behavior (overwriting same key). No contradiction with 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 description is extremely concise—three sentences, no wasted words. It front-loads the core purpose and then provides specific usage guidance and behavioral details efficiently.

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 tool with two string parameters and no output schema, the description covers all necessary context: purpose, usage, behavior, persistence, and relationship with siblings. Nothing 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 baseline is 3. The description provides meaningful examples of keys (e.g., 'subject_property', 'target_ticker') that help the agent understand parameter usage, adding value beyond the schema.

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

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

The description clearly identifies the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples of when to use (resolved ticker, target address, user preference) and distinguishes from sibling tools like 'recall' and 'forget'.

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 usage guidance is given: 'Use when you discover something worth carrying forward.' It also explains when to pair with 'recall' and 'forget,' and clarifies persistence differences between authenticated and anonymous sessions.

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/openWorld/idempotent/non-destructive. The description adds substantial behavioral context: internal cascade through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI is unavailable, the assertion of nothing with figi_candidates on ambiguous matches, explicit `unresolved` reporting, and ISIN-to-legal-entity mapping behavior. No contradiction with 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 description is front-loaded with examples and the core guidance, but is dense and contains long nested parentheticals (e.g., the FIGI multi-match explanation) that reduce scannability. Every sentence carries useful information, but the structure could be tightened for an agent to parse quickly.

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 full burden of explaining return behavior, and it does: it lists all identifier outputs per type, names the figi_candidates and unresolved fields, describes ownership data, provides a citation format for RxNorm, and covers input constraints. For a two-parameter tool with this level of underlying complexity, nothing critical 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, but the description adds meaning beyond the schema: ISIN accepted for company, exact-ticker-map vs name-search behavior for FIGI, the requirement to pass only the issuer name (with a concrete warning against trailing security-class words), and the brand/generic input handling for drug. This materially helps an agent construct correct calls.

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

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

The description clearly states a specific verb and resource: resolve a user-spoken NAME to canonical/official identifiers that other tools require as input. It differentiates itself from siblings by positioning it as the entry-point lookup tool, and enumerates supported types (company, drug) and output identifiers (CIK, LEI, FIGI, RxCUI).

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 'Use FIRST whenever you have a name but need an ID' and explains when it replaces multiple manual lookups. However, it does not explicitly name alternatives or state when NOT to use it (e.g., if you already have an ID, use entity_profile), leaving a small inference gap.

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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density, fully disclosing the internal process and output structure without contradiction.

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

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

Two sentences, front-loaded with the main action: 'Compare AI visibility across multiple entities side-by-side.' No extraneous words; every sentence provides essential information.

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

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

Given the tool's moderate complexity (multiple entities, ranking, optional parameters), the description covers purpose, process, and output format sufficiently. The schema handles parameter details, so the description does not need to repeat them. The tool is well-documented.

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 value by explaining that the first entity is treated as the 'subject' for narrative, which is not in the schema. However, it does not elaborate on optional parameters like models or context, but those are adequately described in the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes and ranking. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different domain) by specifying the competitive audit use case.

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 explicitly recommends use for competitive AI-marketing audits with an example question. It implies usage context but does not provide explicit exclusions or alternatives to sibling comparison tools like compare_entities, slightly reducing clarity.

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?

Discloses important behaviors beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This adds significant context that annotations (readOnlyHint, etc.) do not cover.

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 comprehensive and well-structured, though slightly long. It effectively front-loads the core purpose and then covers scope, behavior, and output. Every sentence adds value, but could be tightened slightly.

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?

Despite having only 2 parameters and no output schema, the description thoroughly covers return values (summary block, per-advisory detail, links, alternative versions), ecosystem scope, and potential delays. It is complete for the tool's complexity.

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. Description adds context: explains that version defaults to latest, mentions what the tool returns (summary block, alternative versions), helping agents decide on parameter use. Provides marginal value beyond schema.

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

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

The description clearly states it is a composite check for npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings like artist or bet_research by being a specialized npm dependency evaluation tool.

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 tells when to use: when an agent asks about safety, popularity, or size of an npm package. Also specifies when not to use: for non-NPM ecosystems like PyPI, Maven, etc., directing to deps.dev:version directly.

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, idempotentHint, and destructiveHint false, so the description adds little behavioral context. It does not contradict 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 description is a single concise sentence with no wasted words. It could be slightly more informative but is efficient.

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 presence of an output schema and simple functionality, the description is adequate. However, it lacks context on pagination or case sensitivity.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add meaning beyond listing content types, so baseline score is appropriate.

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

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

The description clearly states it searches Deezer for tracks/albums/artists/playlists, specifying the resource and action. However, it does not differentiate from sibling tools like search_within or deep_research.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention any prerequisites or exclusions, leaving the agent to infer usage.

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?

Discloses beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flag), output details (character offsets, similarity scores). No contradiction with 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?

Single paragraph, front-loaded with the core action. Every sentence adds essential information (use case, workflow, technical details). No fluff.

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?

Despite no output schema, description adequately explains the return format (top-N passages with offsets and scores). Covers constraints, model, and usage context sufficiently for a tool of this complexity.

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 has 100% coverage; description adds examples for 'query' parameter and clarifies the 'text' limit. For 'limit', schema already specifies range and default. Incremental value is moderate.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, tool result). It explains the utility when the record is too large for the prompt, distinguishing it from other search tools by focusing on internal search within already-fetched content.

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 states when to use: 'Use when the record is too big to cram into the prompt.' Provides a workflow with a sibling tool (ask_pipeworx_grounded), giving clear guidance on integration and context.

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 richly details behavioral traits: subscription persistence, delivery channel constraints (phone verification, SMS cap, webhook signing and auto-disable), all of which go beyond the annotations. No contradictions with 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 description is well-organized and efficient, though slightly verbose in the delivery section. However, it is front-loaded with the core purpose and adds necessary detail. Could be more concise by moving some examples to schema descriptions, but acceptable.

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?

The description covers most aspects: prerequisites, type options, delivery channels with constraints. It lacks explicit mention of the full return structure (e.g., that response includes subscription id and optional webhook secret), but the webhook secret is mentioned as 'returned once at subscribe time' in delivery.webhook description. Overall, it is sufficiently complete for this complex 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?

The description provides extensive parameter semantics beyond the schema, including concrete filter examples for each subscription type, items codes, delivery channel specifics (webhook signing, phone verification, rate limit). Schema coverage is 100%, but description adds substantial 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?

The description uses specific verb 'Create' and resource 'proactive monitoring subscription', and explicitly states it returns the new subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description clearly states the prerequisite (OAuth account) and gives examples for each subscription type, but does not explicitly contrast with sibling tools like list_subscriptions or ask_pipeworx for ad-hoc queries. However, the usage context is well defined.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by detailing that the tool returns curated example questions with exact tool calls, drawn from a live catalog, and that the output adapts to the optional 'topic' parameter.

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 front-loaded with user-facing phrases ('What can I ask...?') followed by a concise explanation of functionality and usage. While slightly verbose, it avoids redundancy and every sentence adds information.

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

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

Given only one optional parameter, no output schema, and a large sibling list, the description is complete. It covers the purpose, return type, optional parameter usage, and when to invoke the tool, leaving no ambiguity for an AI agent.

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% for the single 'topic' parameter. The description goes beyond the schema by listing example topic values ('finance', 'pharma', etc.) and explaining the behavior when omitted (full cross-category spread), adding semantic 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?

The description uses specific verbs ('returns category-bucketed example questions') and clearly identifies the resource ('Pipeworx onboarding entry point'). It distinguishes from sibling tools like 'ask_pipeworx' or 'search' by positioning itself as the entry point for discovering what the agent can do.

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 states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear context for when to invoke the tool, though it does not mention specific alternatives or 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?

Annotations already indicate readOnlyHint: true and destructiveHint: false, so the description's minimal 'Track metadata' aligns with a read operation. However, the description adds no additional behavioral details beyond annotations, such as error handling, rate limits, or partial results. With annotations covering the basic safety profile, the description does not enhance transparency.

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 extremely concise (5 words) and front-loaded with the core action. It is not verbose, but it could benefit from a bit more structure, such as an example or context. However, for a simple lookup tool, this level of conciseness is nearly optimal.

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 that there is an output schema (not shown) and one required parameter with annotations providing safety hints, the description is minimal but sufficient for a straightforward ID-based lookup. However, it does not mention what kind of metadata is returned or any potential errors, leaving some gaps in completeness.

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

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

The description specifies 'by Deezer track id,' which gives semantic meaning to the sole parameter 'id' beyond its type (number) and required status. It clarifies that the ID is a specific Deezer track identifier, which is crucial for correct usage. With 0% schema description coverage, this compensation is valuable.

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 'Track metadata by Deezer track id,' which clearly indicates the tool retrieves metadata for a specific track from Deezer. It differentiates from sibling tools like 'album' or 'artist' by specifying the entity type (track) and data source (Deezer). Slight ambiguity in verb usage but overall clear.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when not to use it. This leaves the agent without context for selection among many similar data retrieval tools.

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

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

Adds that the row is deactivated not deleted, and ownership enforcement, beyond annotations which only provide destructiveHint false and idempotentHint true.

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

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

Two sentences with no wasted words, efficiently conveying purpose, constraints, and behavior.

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

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

For a single-parameter tool with no output schema, the description covers essential behavioral details (soft delete, ownership) and is sufficiently complete.

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

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

Schema coverage is 100% with clear parameter description. The description adds minimal extra value beyond the schema, meeting the baseline.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource, and distinguishes from siblings like subscribe and list_subscriptions.

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 mentions ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior, providing context for when to use this tool versus 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?

Beyond the read-only, non-destructive annotations, the description explains the two routing paths, the exact verdict values, that could_not_verify is a non-evidential failure carrying verification_error, and that unsupported means no source covers it. It also reveals it returns verbatim evidence with citations and reasoning. This is substantial behavioral disclosure not present in 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?

The description is dense but front-loaded with concrete query examples, uses bolded actionable warnings, and every sentence adds purpose, scope, or behavioral nuance. The 'IMPORTANT for callers' block is well-structured and keeps the most critical error semantics prominent.

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 tool's complexity, the description fully covers what the agent receives (verdict enum, actual value with citation, reasoning), how errors are signaled, and how to interpret edge cases. With no output schema, the description carries the full burden of return-value explanation and meets it completely.

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%, but the description adds significant semantic value beyond the property descriptions: it explains how tolerance_pct overrides the claim-wording tolerance, caps the default at 5%, and suggests setting 1–2 for hallucination detection. This helps the agent choose parameter values correctly.

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

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

The description states a specific verb ('verify/confirm/refute') and resource ('natural-language factual claims against authoritative sources'), and distinguishes the tool from siblings by documenting its dedicated routing for company-financial vs. other claims. It also contrasts with generic lookups by noting it replaces 4–6 sequential calls.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It details when each internal path (SEC EDGAR fast path vs. grounded pipeline) applies and clarifies that could_not_verify/unsupported are different failure modes, providing clear usage context and exclusions.

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