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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: routes across 5,529 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. 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 long but dense, front-loading the key guidance ('PREFER OVER WEB SEARCH') and then providing justification and examples. Every sentence adds value, though it could be trimmed slightly without losing meaning.

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 explains the return format (structured answer with citation URIs) and covers usage context, performance characteristics, and fallback alternatives. For a complex routing tool, this is remarkably 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% and all parameters are aliases of 'question', so the schema already documents them well. The description adds example questions but no additional parameter-level semantics, maintaining the baseline for full schema coverage without extra parameter detail.

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 answers factual questions from authoritative sources and routes to the right tool, with a specific verb (answer, route) and a well-defined resource scope. It explicitly distinguishes itself from siblings by positioning as the default entry point and naming alternatives like ask_pipeworx_grounded and 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?

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and tells when to step up to alternatives with specific names and conditions. Also gives concrete examples of query types, making the appropriate context crystal 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?

While annotations already declare read-only, open-world, idempotent, and non-destructive behavior, the description adds essential context: candidate routing improvements are enabled live when under test, currently no candidate is active so it matches ask_pipeworx exactly, and it is a fully functional router. This provides behavioral nuance beyond the structured hints.

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 four sentences long and front-loads the key identity ('Beta version of ask_pipeworx'), then explains the routing mechanism and current status. While slightly verbose with specifics like the exact tool count, each sentence contributes distinct information, making it efficient without being overly terse.

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 the beta status, current active state (no candidate), usage instructions, relationship to the stable router, and clarifies that it is a full working router. Given the rich annotations, fully documented schema, and explicit reference to the identical response shape, all necessary context is provided for an agent to select and invoke the tool correctly.

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

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

The input schema fully documents all six parameters, all as aliases for the required 'question', with 100% coverage. The description adds no parameter-level information, so the baseline score of 3 is appropriate; the schema alone provides sufficient semantic detail.

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 explicitly states this is a beta version of ask_pipeworx, described as an identical universal router with the same 5,529 tools and response shape. It further distinguishes itself from siblings by identifying its experimental edge and candidate routing improvements, making the purpose and relation to other tools 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?

The description gives direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, establishing an explicit scenario for choosing this over ask_pipeworx. The note that it is a full working router (not a fallback) clarifies potential misconceptions.

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 (read-only, open-world, idempotent), the description discloses the internal routing process, the grounding constraint ('using ONLY what the tool result contains'), the refusal behavior with specific refusal_reason enums, and the cost trade-off of one extra LLM call. This enriches the agent's understanding of failure modes and trust boundaries.

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, followed by process, output contract, usage guidance, and trade-off. Each sentence adds a distinct piece of information without redundancy or filler, making it appropriately sized for the tool's complexity.

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

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

The tool has no output schema, but the description supplies a detailed return structure and enumerates refusal reasons. It covers the full workflow, decision context, and limitations, making it self-sufficient for an agent to invoke and interpret results 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?

The input schema already documents all six parameters as aliases for a natural-language question, achieving 100% coverage. The description adds no information about parameter syntax or semantics, so it remains at the baseline 3 for high schema coverage.

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 hallucination-resistant answer mode for high-stakes reads, with a specific verb ('EXTRACTS the answer') and resource (tool results). It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction using only tool result 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 whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Also names the alternative tool, providing clear decision 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 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 read-only, open-world, and idempotent, so the description goes further by detailing the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] behavior ('never invented'), contradictions[] for standard/thorough, 'hop' field, citation_uri resolvability, semantic excerpting, and expected latency. It also discloses the account/payment requirement, which is not in annotations. No contradiction 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 every sentence carries useful information—account requirements, data scope, tool routing, output packet, gaps, exclusions, depth semantics, timing. It is front-loaded with the most critical constraint (account required) and alternates. Some information is repeated (e.g., contradictions for standard/thorough appear twice), but the density and organization earn a 4, not a 5, because trimming ~20% would improve scannability 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?

This is a complex tool with no output schema, so the description carries the full burden of explaining inputs, behavior, and outputs. It covers the return format (findings packet with fields), edge cases (gaps[], contradictions[], unresolved citations), timing (15-90s), and the difference from open-web search. It even explains when citations are present (only when resolvable). Given the tool's complexity, the description is remarkably 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% for both parameters, so the baseline is 3. The description adds meaningful context beyond the schema: it elaborates on the depth enum with facet counts, hop behavior, gap recovery, contradiction scanning, and paid tier for 'thorough', and it clarifies that 'question' accepts broad/multi-part natural language. Slight redundancy exists (contradictions mentioned for standard/thorough in both description and schema), but the added semantic value justifies a 4 rather than 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 uses the specific verb 'research' and clearly identifies the resource: Pipeworx's 1455 structured data sources. It explicitly differentiates from open-web search and from sibling tool ask_pipeworx by stating 'this is NOT open-web search' and describing the decomposition-and-routing behavior. 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 explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples. It also names alternatives for specific cases: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It even provides a fallback if not signed in: 'use ask_pipeworx instead'. These exclusions and alternatives are model examples.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detailed transparency about data sources fanned across, soft-fail for USPTO, and return fields, 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?

Description is front-loaded with examples and structured into clear sections. While slightly lengthy, it avoids redundancy and earns its paragraphs with useful details.

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 and complexity, description covers return fields (cik, filings, fundamentals, patents, news, LEI) and sources. Missing pagination/rate limits but overall thorough.

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 3. Description adds meaning by explaining the type enum (only company), that value accepts ticker or CIK, and that names are not supported, which exceeds 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 clearly states it provides a 'full cross-source profile of a US public company' with specific examples like 'Tell me about X' and 'research Acme'. It distinguishes from siblings like resolve_entity by noting name resolution is not supported here.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides when-not-to-use: names not supported, requiring resolve_entity first.

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

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

Annotations already 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read operations. The description adds significant context beyond annotations, detailing compatibility_warning cases, temporal_alignment, and skipped_cross counters. 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 well-structured with clear sections (modes, response, safety fields) and uses formatting like capitalization and labels. However, it is somewhat verbose and could be condensed without losing meaning.

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 response structure (leg-by-leg prices, spread array, compatibility fields). It covers parameter interactions, edge cases (compatibility warnings), and temporal alignment, making it sufficiently complete for a cross-venue spread 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% with descriptions for all three parameters. The description adds value by explaining the interaction between parameters (e.g., explicit overrides topic) and providing examples. This exceeds 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?

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same outcome. It uses specific verbs (e.g., 'computes', 'auto-fetch') and distinguishes itself from siblings like `polymarket_arbitrage` by focusing on multi-venue comparison. The two modes (topic and explicit) are clearly explained.

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 explicit guidance on when to use this tool (for comparing prices across venues) and when not to (when bet shapes are non-equivalent, as indicated by compatibility_warning). It also explains that pre-mapped topics are not always tradeable, setting realistic expectations.

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 read-only/idempotent, but the description goes further by disclosing internal multi-endpoint cascading, graceful degradation when upstream sources (GLEIF/OpenFIGI) are unavailable, and explicit reporting of unresolved identifiers. This gives agents a clear mental model of side effects and failure modes.

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

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

Though lengthy, the description is structured with examples first, then core purpose, usage guidance, and per-type details. Every sentence adds distinct value—input formats, output specifics, fallback behavior, and efficiency gains—and front-loads the most actionable instructions.

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?

Without an output schema, the description carries full responsibility for explaining return values. It does so for both types: company returns CIK, ticker, name, LEI with ownership, FIGI, source labels, and unresolved list; drug returns RxCUI, ingredient, brand, and citation. It also covers input formats and degradation, making it sufficiently complete for agent decision-making.

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 already covers both parameters with descriptions and enums, but the description adds depth by specifying acceptable input forms (ticker, CIK, name for company; brand/generic for drug), example formats, and the meaning of the value field for each type. This enhances agent 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?

Description opens with concrete user queries and states the core function: resolving a name to canonical identifiers. It explicitly positions the tool as the first stop when an ID is needed, distinguishing it from sibling tools that operate on resolved entities (e.g., entity_profile, 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?

Provides an explicit when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also contextualizes by noting it 'replaces 2-3 manual lookups' and returns identifiers other tools require. While it doesn't name alternatives, the use case is unambiguous.

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

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

Annotations already 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.