radio

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 valuable context: the default model is Workers AI Llama-3.3-70b (free), Anthropic requires a BYO key with direct billing, and the return structure is detailed. This goes beyond what annotations alone convey.

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 sentences, front-loaded with the core purpose and followed by model configuration and use cases. No redundant or filler text is present.

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

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

The tool has no output schema, so the description compensates by listing the per-model return fields (score, confidence, signals, raw_response) plus a combined view. It also covers default behavior, authentication for Anthropic, and typical use cases, making it complete for an agent to invoke correctly.

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

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

Although schema description coverage is 100%, the description enriches parameter meaning by stating that Workers AI is the free default, that _apiKey is only needed when 'anthropic' is in models, and that omitting models yields just workers-ai. It also clarifies the pay-as-you-go nature of Anthropic calls. This adds value over 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 the specific verb 'Probe' and clearly identifies the resource (LLMs) and output (visibility score 0-100 per model). It distinguishes this from siblings like ask_pipeworx or deep_research by focusing on visibility scoring rather than general Q&A or research. The default model and optional Anthropic key add specificity.

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

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

The description states it is 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving clear contexts where this tool applies. It does not explicitly name alternative tools to use instead, but the use cases are sufficiently distinct from sibling tools. No exclusion criteria are provided.

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 and idempotentHint, and the description adds useful behavioral context: it routes questions across 5,344 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is a fast single call. However, it doesn't disclose potential limitations like rate limits or error handling.

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 'PREFER OVER WEB SEARCH' and efficiently packs examples, alternatives, and scope into a single block. It is somewhat lengthy but every sentence adds value; a more structured layout could improve scannability, but it remains concise relative to 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?

Given the tool's complexity and lack of an output schema, the description fully covers the return format (structured answer with citation URIs), usage examples, and distinctions from alternatives. An agent can correctly select and invoke this tool based on the information provided.

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% since all parameters are aliases for 'question' and are explicitly documented. The description adds valuable examples and clarifies acceptable question formats across domains (SEC filings, FDA data, real estate, etc.), which helps the agent formulate valid natural language inputs.

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 as a question router to authoritative structured data sources, returning answers with citation URIs. It explicitly distinguishes itself from web search and names sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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, including 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also explains when to use alternative tools: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions, plus coverage of breaking news.

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, and non-destructive behavior. The description adds valuable context about beta status, active/inactive candidate routing, and the fact that it is a fully functional router, going 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?

Four sentences, each serving a purpose: beta identity, current state, usage direction, and fallback reassurance. Slightly verbose but appropriate for conveying the experimental context clearly.

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 beta nature and lack of output schema, the description thoroughly covers what the tool does, its current status, how to use it, and what to expect in terms of response shape (same as ask_pipeworx). It is complete for an experimental router.

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 schema covers all 6 parameters (aliases for 'question') with 100% description coverage. The description only references 'same arguments' as the stable tool, which adds no new semantic detail beyond what the schema already provides.

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 as a beta version of ask_pipeworx, a universal router with the same 5,344 tools and arguments. It distinguishes itself from the stable sibling by emphasizing the experimental routing improvements and current matching behavior.

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

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

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and mentions that results are compared against the stable router. This provides clear guidance on when to choose this beta tool over the stable alternative.

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

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

The description discloses critical behavioral traits beyond annotations: it uses only the tool result to extract answers, explicitly refuses with structured reasons when the data doesn't directly answer, and incurs an extra LLM call. This extends far beyond the readOnlyHint/idempotentHint annotations and informs the agent about potential refusals and output structure.

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 the core purpose, and every sentence provides essential information. It avoids fluff, delivering a dense but clear explanation of the process, output format, refusal reasons, usage guidance, and cost trade-off. The sentence count is justified by the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly covers both success and refusal formats (including specific refusal reasons), and provides usage context, alternatives, and cost. Given the tool's internal routing complexity, the description is remarkably complete without an 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?

The input schema has 100% coverage for all six parameters (question and aliases) with clear descriptions. The tool description adds no additional parameter semantics, only restating that the question is in natural language, which the schema already conveys. The baseline of 3 applies since the schema fully documents parameters.

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

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

The description clearly states a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mode's unique behavior (grounded extraction from tool results) and distinguishes it from the sibling tool ask_pipeworx by explicitly noting the extra cost and higher-stakes use case. This provides clear differentiation.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative (ask_pipeworx) and advises preferring it for casual lookups due to cost, providing clear usage boundaries 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 annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds extensive behavioral detail beyond that: fan-out patterns, resolver contract with match confidence, parent-event extraction, news fallback fields, blocking safety routes for low-confidence/closed markets, and cancellation-rule parsing. It explains edge cases and failure modes thoroughly, giving the agent a complete mental model.

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 it is exceptionally well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and the core purpose is front-loaded in the first sentence. While every sentence adds valuable detail, the length pushes the boundary of conciseness; a more compact summary could have been provided without losing essential nuance, but the exhaustive sections are justified by the tool's complexity.

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

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

With no output schema, the description fully compensates by detailing the response structure: result.market, result.analysis, result.evidence, match confidence levels, parent_event fields, news metadata, and status strings for edge cases. It also covers safety mechanisms and cancellation-rule risks, making it one of the most complete tool descriptions possible for a complex research 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%, so the baseline is 3, but the description adds significant meaning beyond the raw field definitions. It explains how the 'market' parameter accepts slugs, URLs, or question text and illustrates fan-out examples for various bet types (BTC, Fed, Hormuz, Yankees, NVDA-vs-AAPL). This contextualizes the 'depth' parameter and clarifies how inputs are interpreted, going beyond the schema's simple type/enum 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 starts with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' — a specific verb and resource that clearly defines the tool's core function. It immediately distinguishes itself from siblings like polymarket_arbitrage or polymarket_edges by focusing on per-bet research with data fan-out, and lists explicit use cases like 'should I bet on X'.

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 usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also explains what happens in specific scenarios (low-confidence matches, closed markets, wide spreads), giving agents strong situational guidance. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Despite annotations already declaring the tool read-only, open-world, idempotent, and non-destructive, the description adds substantial behavioral detail: it pulls LATEST 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years, sources FAERS/FDA/trial counts for drugs, sorts by primary metric, and returns citation URIs. This exceeds 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 dense and front-loaded with trigger phrases, then quickly moves to scope and data-source details. The parenthetical examples (AAPL Sep, NVDA Jan) add useful context but could be trimmed without losing core meaning; otherwise every sentence provides 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?

For a tool with only two parameters, no output schema, and strong annotations, the description is very complete: it covers entity types, count limits, data sources, sorting behavior, return value (paired data + citation URIs), and performance benefit over alternatives. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful examples for both parameters: tickers/CIKs for companies and drug names for drugs, plus high-level semantic context about what data is fetched per type. It doesn't add syntax details beyond the schema, but it amplifies the schema's meaning.

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 2–5 companies or drugs in a single parallel call, using an explicit verb ('compare') and resource types. It distinguishes itself from siblings by emphasizing it ALWAYS PREFER[s] over sequential single-pack lookups and by listing concrete trigger phrases.

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 specifies when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides trigger examples ('X vs Y', 'rank these companies'). It also constrains usage to 2–5 entities and differentiates behavior for 'company' vs 'drug'.

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

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

Beyond the annotations, the description discloses account requirements, parallel facet decomposition, that it is NOT open-web search, returns gaps[] (never invented), second-hop iteration details, contradictions[] detection, semantic excerpting, and expected response times. It thoroughly describes the tool's behavioral profile.

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 and well-structured, front-loading the account requirement before explaining purpose, alternatives, and behavior. It is lengthy but the complexity of the tool justifies most content; however, there is some redundancy with the schema's depth explanation, keeping it from a 5.

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

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

For a tool with no output schema, the description is exceptionally complete: it details the return format (findings packet, gaps[], contradictions[], hop field, citation_uri), account prerequisites, depth modes with timing, and handling of large records. No important aspect is left unexplained.

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

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

The schema covers 100% of parameters with detailed descriptions, including depth enum semantics. The tool description adds no additional parameter-specific meaning beyond what the schema already provides, so the baseline of 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 explicitly states the tool performs 'grounded multi-source research' across Pipeworx's 1393 STRUCTURED data sources in one call, distinguishing it from sibling tools by explicitly contrasting with ask_pipeworx for single lookups and breaking news. The verb 'research' plus the concrete resource (structured data sources) makes the purpose 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 usage scenarios: 'best for broad/multi-part questions over structured data' and for single lookups says 'use ask_pipeworx instead', for breaking news 'prefer ask_pipeworx'. It also names alternatives and explains account/depth prerequisites, offering 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond this: it returns top-N results with 'names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This clarifies the output format and usage pattern without contradicting 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 front-loaded with its primary purpose and then lists supported domains—necessary for a discovery tool. It is longer than minimal but each sentence earns its place: supported categories, return format, and usage recommendation are all valuable. The structure is logical and not redundant with schema fields.

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

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

There is no output schema, but the description compensates by detailing exactly what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also explains why to call this first. It omits edge cases like empty results or error behavior, but for a read-only discovery tool with strong annotations, the description is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including aliases and the limit. The description adds minimal extra parameter semantics—only the phrase 'top-N' implies the meaning of limit, but the schema already states 'Maximum number of tools to return (default 20, max 50).' Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly differentiates from siblings by being the meta-tool for discovering other tools, and the explicit list of supported domains (SEC filings, financials, FDA drugs, etc.) leaves no ambiguity about 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?

It gives explicit 'Use when' guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This effectively tells the agent to use it before directly invoking specific tools, though it doesn't name explicit alternatives or state 'don't use this when you already know the exact 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?

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses concrete behaviors: it fans out across specific sources, returns a defined set of fields, notes the USPTO PatentsView API sunset with soft-fail behavior, and explains the GDELT→GNews fallback. This is rich, non-obvious context that annotations alone cannot convey.

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 efficiently dense, front-loaded with natural-language examples and structured with semicolon-separated return fields. It earns its length given the multi-source complexity, though a bit more partitioning would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining return values, sources, fallback behavior, and limitations. It thoroughly covers what the agent will get (cik, filings with URIs, fundamentals, patents, news, LEI) and how to interact with the tool, making it complete for a complex fan-out 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% and the schema already documents ticker/CIK formats, zero-padding, and the resolve_entity prerequisite. The description repeats those details without adding new semantic nuance, so it meets the baseline but does not elevate it.

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 concrete natural-language triggers and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (companies) and the action (profile/brief/rundown), and the fan-out scope distinguishes it from siblings like compare_entities or resolve_entity.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and a hard limitation is stated — names are not supported, so use resolve_entity first if only a name is available. This covers both when-to-use and when-not-to-use.

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 destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds value beyond annotations by highlighting privacy relevance ('clear sensitive data') and lifecycle context ('task is done'). It does not contradict the annotations, and the extra context justifies a score above the baseline.

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 sentences, each serving a distinct purpose: the action, the usage context, and the relationship to sibling tools. Every sentence earns its place with no redundancy or filler.

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

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

Given the simple single-parameter schema, strong annotations (destructive and idempotent), and no output schema, the description covers all needed aspects: what it does, when to use it, and how it relates to remember and recall. It paints a complete picture for the 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 for the single 'key' parameter is 100% with the description 'Memory key to delete'. The tool description merely says 'by key', which adds no additional semantic info beyond the schema. Per the rubric baseline, this is exactly a 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 'Delete a previously stored memory by key,' which uses a specific verb ('delete'), a resource ('memory'), and the key parameter. It also distinguishes itself from siblings by explicitly mentioning 'remember' and 'recall' as complementary tools, making it clear this is the deletion counterpart.

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 when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), giving clear alternatives and 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds operational details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output as 'a single text blob ready to drop at site-root/llms.txt', which goes 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 well-structured with a clear first sentence stating the purpose, a process explanation, output description, and use cases. It is somewhat longer than strictly necessary, but every sentence contributes 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?

For a simple read-only tool with two parameters and no output schema, the description covers the input, process, output format, and use cases. It does not detail the exact llms.txt syntax, but 'standard llms.txt markdown format' is sufficient for a competent agent. The schema already specifies max_links defaults and limits.

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 both parameters (url and max_links) fully described. The description reinforces the url purpose ('any URL') but does not significantly add meaning beyond the schema. Baseline of 3 is appropriate since the schema carries the parameter semantics.

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 action: 'Generate a production-ready llms.txt file for any URL'. It specifies the resource (llms.txt) and the verb (generate), and differentiates from siblings like scan_competitor_ai_presence by focusing on output generation rather than scanning presence.

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 lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool, though it does not explicitly mention alternatives or exclusions.

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, non-destructive, and idempotent behavior. The description adds meaningful context about the selection criteria ('trending', 'ranked by popularity') and the exact return fields, which goes beyond simple annotation coverage.

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 two sentences, front-loaded with the verb and resource, and contains no unnecessary words. It efficiently conveys purpose, optional filter, and return content.

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

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

Given the simple tool, rich annotations (read-only, idempotent), existing output schema, and concise description covering core behavior and filter, there are no significant gaps. The description is adequate for correct invocation.

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

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

Schema covers both parameters with descriptions and defaults (100% coverage), so baseline is 3. However, the description's country examples use ISO codes ('US', 'GB', 'DE') while the schema specifies country names ('Germany', 'United States'), introducing ambiguity about the accepted format and potentially misleading the agent.

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 the tool retrieves trending radio stations ranked by popularity with optional country filter. It distinguishes itself from sibling 'search_stations' by focusing on trending/popular rather than search, and mentions the specific output fields (URLs, genres, vote counts).

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 conveys the use case: get trending/popular stations, optionally filtered by country. It provides clear context but does not explicitly mention alternatives or when not to use this tool relative to siblings like search_stations.

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 safety profile is well covered. The description adds the return content (country names and station counts), which is useful, but does not discuss other behavioral aspects like ordering, pagination, or data freshness. Given the strong annotations, this is adequate.

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 sentences, with the first stating the primary action and the second detailing the return value and purpose. There is zero filler, and the key information is front-loaded.

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 no-parameter, read-only listing tool with an output schema, the description fully explains what the tool does and why it is useful. It even describes the return value despite the output schema existing, which adds clarity without being redundant. No gaps are apparent.

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 tool has zero parameters, so there is nothing to explain. Baseline for 0 params is 4, and the description does not attempt to artificially introduce parameter concerns. The schema coverage is trivially 100%.

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 lists countries with radio stations and returns country names and station counts. The verb 'Browse' and the resource 'available countries' make the purpose unambiguous, and it distinguishes itself from sibling tools by focusing on country-level geographic targeting.

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 implies when to use this tool (to target searches geographically) but does not explicitly mention alternatives or exclusions. It gives clear context for a simple listing tool, but could be stronger by naming when not to use it (e.g., when you already know the country or need to filter stations).

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds the return field list, the 'active' scope, and the caller-specific nature, enriching context beyond the annotations 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?

Three sentences, each with a distinct purpose: purpose, return shape, and usage. No filler or redundancy; the main verb is front-loaded.

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 list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context sufficiently. Combined with annotations and schema, the tool is fully described.

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 parameter, with a full description already. The description's mention of 'active' subscriptions complements the include_inactive parameter but does not add new parameter semantics beyond the schema.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), and explicitly enumerates return fields, clearly distinguishing this from sibling subscribe/unsubscribe 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?

Provides explicit use cases: to review what you're monitoring before adding more, and to find an ID to cancel. It does not explicitly name alternative tools but implies subscribe/unsubscribe, so no exclusions are stated.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: the results are ranked by station count and the tool serves an exploratory discovery purpose. 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?

Two succinct sentences: the first announces the core purpose and ranking behavior, the second gives a practical usage note. Every word earns its place, and the description is front-loaded with the 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 simplicity (one optional parameter, rich annotations, and an output schema for return values), the description is fully adequate. It covers what the tool does, when to use it, and adds ranking behavior; no gaps are apparent.

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 only parameter (limit) is fully documented in the input schema with type, description, and default. The tool description adds no additional parameter semantics, but with 100% schema coverage, a baseline of 3 is appropriate per the rubric.

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 'Discover', names the resource 'radio genres and tags', and specifies a ranking criterion ('ranked by station count'). This clearly distinguishes it from sibling tools like list_countries or get_top_stations.

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

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

The description states a clear use case: 'Use to explore what categories are available before searching.' This tells the agent when to use the tool, but it does not explicitly name alternatives or exclusions, stopping short of the highest tier of 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 only provide negative hints (readOnlyHint false, destructiveHint false), so the description carries the burden of behavioral disclosure. It adds valuable context: rate limit of 5 per identifier per day, free usage not counting against tool-call quota, and that the team reads digests daily with roadmap impact. This goes beyond what annotations or schema 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?

Two sentences front-load purpose, then provide usage rules, message guidance, and constraints. Each clause adds unique information with no filler. Slightly dense but 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?

For a feedback tool with no output schema, the description covers the core aspects: what it is, when to use it, how to phrase feedback, rate limits, and quota implications. The nested context object is self-explanatory from the schema. It doesn't mention response/confirmation behavior, but that's not critical for a free feedback submission 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 already describes all 3 parameters at 100% coverage. The description enhances this by adding message-writing guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' and 'Be specific (which tool, what error)') that isn't derivable from 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?

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature, data_gap, praise) and clearly distinguishes this tool from sibling catalog/data tools by positioning it as a feedback channel rather than a data lookup.

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

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

Explicit 'Use when' clauses map scenarios (wrong/stale data, missing tool, praise) to feedback types, and instructions to describe issues in terms of tools/packs while avoiding user prompts provide concrete decision rules. It doesn't explicitly state when not to use it, but the coverage is strong enough that no exclusions are necessary.

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 valuable behavioral context beyond the annotations: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on the window. It also clarifies the returned data format, which is not covered by an output schema. 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 concise and well-structured: a compelling opening sentence, a clear return statement, a useful list of use cases, and a final note on data source and caching. Every sentence adds distinct value with no 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?

For a tool with one optional parameter and no output schema, the description is remarkably complete. It explains the purpose, the returned data (top tools, top packs, total call volume), the data format (pack, tool, count), and the caching behavior, giving an agent everything needed to invoke it correctly.

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

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

The input schema already provides full coverage for the single 'window' parameter, including a description of the trade-off between shorter and longer windows. The tool description only restates the options ('24h, 7d, or 30d') without adding new meaning, so it relies on the schema's 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 what the tool does: it reports what other AI agents are calling on Pipeworx right now, returning top tools, top packs, and total call volume over a recent window. This specific verb ('returns') and resource ('top tools, top packs, total call volume') distinguish it from sibling tools like discover_tools or ask_pipeworx.

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 concrete use cases: discovering hot data sources, confirming canonical tool choices, and aligning with agent needs. This gives clear context for when to use the tool, though it does not explicitly name alternatives or 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?

Annotations already declare read-only and non-destructive, but the description adds significant context: partition filter drops placeholder slugs, fill check evaluates realizable edge against live order book, and 'skipped_low_similarity surfaces the rejected pair count'. These behavioral details go beyond annotations and help the agent assess side effects and reliability.

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 well-structured, front-loaded with the core purpose and then organized by mode, filter, response, and fill check. Every sentence adds value, though some details (e.g., exact threshold '>3pp' and '≥0.30 Jaccard') could be trimmed for conciseness without losing essential guidance.

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 complex two-mode tool with no output schema, the description is remarkably complete. It covers inputs, modes, filtering logic, response structure (opportunities[], partition_check{}), and the critical fill-check caveat for tradability. It even explains the semantic anchor to prevent false pairings, leaving no major gaps for an agent to mis-invoke.

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 basic descriptions, but the tool description enriches both parameters: event explains it walks child markets and runs partition_check, topic describes cross-event search and Jaccard similarity constraint. It also reveals that zero args triggers trending_scan, which is not in the schema. This is substantial added meaning.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (trending_scan, event, topic) and references sibling tools like polymarket_fill_risk for custom sizing, making its niche explicit.

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 concrete when-to-use guidance: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also explains when not to trade via the fill check and directs to polymarket_fill_risk for sizing, effectively covering alternatives and exclusions.

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?

Given the readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral detail: it explains the response structure, the three model families, diagnostics to inspect empty segments, caching ('Cached 1h at the KV level keyed on all knobs'), and a warning that the edge may already be in the price. This goes far beyond the annotations and helps the agent understand side effects and caveats.

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 a clear purpose and then organized into model families, response top-level, knobs, and diagnostics. It is dense and long, but the structure helps an agent navigate the content. Some details (e.g., per-sport α values) are arguably more than necessary, but they do contribute to understanding output semantics.

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

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

There is no output schema, so the description must fully explain return values. It does this thoroughly: the top-level keys (by_segment, fed_candidates/fed_note, _diagnostics), the edge fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the meaning of empty segments are all described. This makes the tool highly invocable and interpretable.

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 covers all 9 parameters with 100% description coverage, so the baseline is 3. The tool description adds extra meaning by explaining how specific knobs affect behavior: 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and 'min_partition_leg_kelly filters partitions by best per-leg Kelly.' This adds value 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage by focusing on edge detection from Pipeworx data rather than arbitrage or tracking.

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 use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also mentions that Fed bets are surfaced but excluded from ranking, giving context on what to expect. However, it does not name alternatives or explicitly state when not to use this tool versus sibling tools.

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

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

Beyond the read-only annotations, the description discloses snapshot write behavior (cache-miss), 60-day TTL, signed edge_pp_net semantics (negative = SELL YES), decay computed from daily closes not intraday, and the meaning of expired opportunities and gaps in snapshot_dates.

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 well-structured with clear sections: purpose, args, response, limits. Every sentence adds value, front-loaded with the core question, and the labels (RESPONSE, LIMITS) aid scannability.

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 thoroughly explains the response structure (tracked, expired, snapshot_dates), field semantics, edge cases (cache-miss gaps, TTL bound), and limitations (daily closes, not intraday). Nothing critical is missing for an AI agent to use the tool correctly.

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

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

Schema already covers both parameters with 100% coverage and defaults. The description restates defaults and adds the phrase 'snapshot family' for window, but no additional syntax or format details beyond the schema are provided, 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 clearly states the tool's purpose: edge persistence and decay telemetry, answering whether an edge is shrinking and for how long it has existed. It distinguishes from sibling tools by focusing on time-series analysis of snapshots rather than current edge values.

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 use context via the direct question it answers and the interpretation of fresh versus old edges. It does not explicitly name alternatives or exclusions, but the built-from-polymarket_edges framing implies when to use this instead of the edge computation 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 (readOnlyHint, destructiveHint) already indicate a safe read-only operation. The description adds substantial context: walks the order-book ladder, computes slippage, returns verdicts (clean/degraded/cannot_fill), identifies thin legs, and explains the outcome of partial fills. 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?

Although long, the description is densely packed and organized: single-market and basket modes are clearly delimited, outputs are enumerated, and the usage warning is highlighted with capitals. Every sentence adds value; 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?

The tool has two modes, four parameters, and no output schema, yet the description lists all major return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, capture_ratio, profit_usd, thin_legs, etc.), covers edge cases, and explains the dominant loss mode. It is self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, but the description enriches every parameter: clarifies side meanings for both modes, size_usd interpretation (max spend vs target proceeds vs settlement notional), default values, and the mutual-exclusivity of market vs event. This goes well beyond the schema's field 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools by naming polymarket_arbitrage and polymarket_edges and positioning itself as the pre-trade validation step.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and warns about partial fills converting arb to directional risk.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by detailing edge-case behaviors: compatibility_warning conditions, matched_pairs logic, temporal_alignment, skipped_cross_type/subtype counters, and the meaning of aligned:false. This provides deep transparency into how the tool handles non-equivalent bet shapes and unrelated events.

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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, covering purpose, usage, response format, and safety warnings. Despite length, it remains organized and front-loads the core purpose.

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 fully explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment) and addresses complex scenarios like non-equivalent bet shapes and temporal gaps. 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?

Although schema coverage is 100%, the description adds substantial meaning: it explains the two mode semantics (topic vs explicit), the auto-fetching behavior for 10 macro shortcuts, and the override relationship between explicit tickers and topic. This contextualizes parameters beyond the schema's simple lists.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resources (Kalshi and Polymarket) and the action (computing spread), distinguishing it from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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 clear context on how to use the tool via two modes (topic shortcuts vs explicit tickers) and warns that pre-mapped topics often return compatibility_warning and are 'pre-mapped ≠ tradeable.' However, it does not explicitly compare against alternatives or state when not to use this tool in favor of a specific sibling.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), the description adds scoping details ('anonymous IP, BYO key hash, or account ID') and the list-all-keys behavior when key is omitted. This is valuable behavioral context not available from annotations alone.

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 sentences, front-loads the core behavior, and each sentence adds meaningful information. There is no filler or repetition.

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 lacking an output schema, the description sufficiently conveys what the tool returns (a value or list of keys) and provides context about scoping and integration with 'remember' and 'forget'. It is complete for a simple retrieval 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% and the schema description already explains that key is a memory key to retrieve (omitting lists all). The description repeats this information but adds illustrative examples of key values ('target ticker, an address, research notes'), which adds slight semantic enrichment but does not significantly go 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 states the tool retrieves a value saved via 'remember' or lists all keys when the key argument is omitted. It uses specific verbs ('retrieve', 'list') and distinguishes itself from sibling tools '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 states when to use the tool ('look up context the agent stored earlier') and contrasts it with alternatives: 'Pair with remember to save, forget to delete.' This gives the agent 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 declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: each alert carries source, citation_uri, and raw event payload, and setting mark_read:true flags events so the next call only shows newer ones. This discloses the side-effect of mark_read and return content 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 three sentences, front-loaded with the core purpose, followed by return content, filtering options, mark_read semantics, and an alternative endpoint. Every sentence contributes meaningful information without redundancy or 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?

Given there is no output schema, the description appropriately describes the returned alert structure (source, citation_uri, raw payload). It also explains the mark_read side-effect and mentions polling suitability and an external endpoint, making it sufficiently complete for an agent to use the tool effectively.

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 each parameter having a description. The tool description adds a minor example for type ('sec_8k') and restates the effect of mark_read, but these do not significantly exceed the schema's own descriptions. It does not compensate for any gaps because there are none.

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 ('Pull fired events from your subscription feed') and clarifies the return content, making it clear this tool retrieves recent alerts. It distinguishes itself from related tools like recent_changes or list_subscriptions by focusing on 'fired events' and 'subscription feed'.

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 usage ('Polls work fine') and an alternative method for the same data (GET registry.pipeworx.io/alerts.json), but it does not explicitly state when not to use this tool or name alternative sibling tools. It implies suitable scenarios without drawing exclusions.

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. The description adds significant behavioral context beyond these: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), notes the PatentsView API sunset causing soft-fail, and specifies the return format (structured changes[] grouped by source + total_changes + pipeworx:// citation URIs).

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

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

The description is dense but well-structured: user-intent examples first, then capability, data-source breakdown, parameter syntax, and return format, ending with an explicit alternative. Every sentence packs useful information, though slightly long due to the fallback and sunset details. Still, nothing is wasted.

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

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

For a tool with this complexity (multiple data sources, fallback logic, time-window parameters, and custom return structure), the description covers all necessary aspects: what sources are queried, how failures are handled, what the return includes, and how to disambiguate from entity_profile. No output schema exists, so the description's mention of changes[] and total_changes is essential and adequate.

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% (all three parameters documented). The description enriches this by showing examples for `since` ('2026-04-01' or '7d', '30d', '3m', '1y') and suggests typical values. It also clarifies `value` accepts ticker or zero-padded CIK and that `type` only supports 'company'. This adds value beyond the raw 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 opens with concrete user intents ('What's new with X' / 'latest on Y') and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes itself from sibling entity_profile by explicitly pointing to the alternative for 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?

Usage guidance is explicit: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also provides contextual recommendations like 'Use "30d" or "1m" for typical monitoring' and explains fallback behavior (GDELT→GNews when rate-limited or 5xx).

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

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

Beyond the annotations (which indicate a non-read-only, idempotent, non-destructive write), the description adds valuable behavioral context: memory is scoped by the agent's identifier, authenticated users get persistent memory while anonymous sessions retain data for 24 hours, and it positions the tool as part of a store/retrieve/delete workflow. These details are not in annotations and significantly 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 four sentences, front-loaded with the core purpose, then usage context, storage details, and related tools. Every sentence adds essential information without redundancy or excessive length, making it highly scannable and 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?

For a simple key-value store with no output schema, the description covers all necessary context: what it does, when to use it, how it's stored (key-value, scoped), persistence behavior, and related tools for retrieval/deletion. Combined with annotations and rich schema, it is fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%: both 'key' and 'value' already have clear descriptions in the input schema. The tool description does not add new parameter-level details, merely restating 'key-value pair' and giving usage examples, which aligns with the baseline of relying on schema for parameter info.

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 with a specific verb and resource: 'Save data the agent will need to reuse later'. It distinguishes itself from sibling tools by naming recall and forget as counterparts, and gives concrete examples of keys (resolved ticker, target address, user preference), leaving no ambiguity about its purpose.

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: 'Use when you discover something worth carrying forward' and lists example scenarios. It also mentions alternatives by pairing with recall for retrieval and forget for deletion, giving clear context without needing to reference sibling descriptions.

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, non-destructive, and idempotent behavior. The description adds valuable context: it cascades through multiple internal endpoints, auto-disambiguates company inputs, and returns specific fields plus citation URIs. This goes beyond annotation metadata and helps the agent understand side effects and output structure.

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 and well-structured, using examples and a clear SUPPORTED TYPES breakdown. It is slightly long but every sentence contributes useful information. The opening example queries make it intuitive without being redundant.

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

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

The tool has two distinct entity types with different output contracts, and the description fully covers both. It explains the return values, citation URIs, and the auto-disambiguation behavior. With no output schema, the description carries the burden of explaining return values, which it does thoroughly.

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, but the tool description enriches parameter meaning significantly. For 'value', it gives concrete examples (AAPL, 0000320193, 'ozempic') and clarifies input formats and auto-disambiguation. The 'type' parameter is explained with supported entity types and what each returns, adding value beyond the schema's enum.

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 like 'resolve' and 'look up' and clearly states the tool maps names to canonical identifiers. It distinguishes itself from siblings by noting it returns IDs that other tools require as input, and details the two supported types (company, drug) with specific output fields.

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 usage guidance: 'Use FIRST whenever you have a name but need an ID.' It provides example queries and explains that it replaces 2-3 manual lookups, making the context clear. It doesn't explicitly mention when not to use it, but the 'FIRST' directive strongly implies it's the entry point for ID resolution.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the safety profile is covered. The description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density—context not present in the annotations. 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?

Three sentences, front-loaded with the primary action, and every sentence adds value: what it does, how it works, when to use it, and what it returns. No fluff or redundancy.

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

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

For a read-only comparison tool with strong annotations and schema coverage, the description is complete. It lists the return format (ranked list with score, confidence, signal density) and the use case. It does not cover error handling or ordering details, but those are not essential given the annotations and tool simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds narrative context (e.g., 'your brand + N competitors') but does not meaningfully elaborate on parameter syntax or formats beyond what the schema already provides. It earns the baseline but no more.

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 ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from the related sibling tool ai_visibility_check. It also states exactly what it does: probes entities, ranks them, and identifies most/least recognized.

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 clear usage context ('competitive AI-marketing audits') with an illustrative example ('does Claude know about us as well as our competitors?'). It does not explicitly list exclusion criteria or alternatives beyond implicitly referencing ai_visibility_check, but the guidance is strong enough to know when 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 the annotations (readOnlyHint, idempotentHint), the description discloses important behavioral details: partial failure degradation, the 5-30s first-measurement latency for bundlephobia, and the presence of a sources_failed field. It also mentions it fans out to multiple sources and returns a structured summary, adding value beyond 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 dense but well-structured. It opens with the core purpose, then usage triggers, then return summary fields, then ecosystem limitations and failure behavior. No redundant sentences; every clause adds new information. Even though longer than minimal, it earns its length given the tool's composite nature.

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 data sources, partial failures, no output schema), the description compensates by enumerating the key return fields (summary block, per-advisory detail, links, alternatives) and the failure mode (sources_failed). Combined with rich annotations and a fully-described schema, the agent has sufficient context 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?

Schema coverage is 100%: both parameters are already described (package as npm name, version as specific version defaults to latest). The description does not add new parameter-level detail; it only contextualizes them within the overall check. Baseline 3 applies because the schema carries the full semantic load.

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 specific purpose: a composite check for whether to add an npm package, fanning out to deps.dev and bundlephobia. It distinguishes itself from siblings by emphasizing the 'ONE call' consolidation and explicitly mentions the data sources and what they provide.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative for non-npm ecosystems.

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 read-only nature is known. The description adds value by disclosing the returned data structure (station name, URL, country, genres, popularity vote count) and that it accepts a keyword for browsing. No contradiction with annotations; the description complements them with functional detail.

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

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

The description is three concise sentences, each serving a distinct purpose: core action, return values, and usage guidance. It is front-loaded with the key action and contains no redundant or filler 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 the tool's simplicity (2 parameters, 1 required), the available annotations, and an output schema, the description is fully adequate. It covers the action, return values, and usage context. Although an output schema exists, the description's mention of return values is a harmless supplement, and no critical behavioral details are 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%: both 'query' and 'limit' have meaningful descriptions, so the baseline is 3. The description text does not add further parameter semantics beyond what the schema provides, such as default values or type details, so it neither improves nor worsens clarity.

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 'Search radio stations by name', which clearly states the action (search) and the resource (radio stations). It also specifies the output fields (name, URL, country, genres, popularity vote count), making the tool's scope unambiguous. This distinguishes it from sibling tools like get_top_stations or search_within by emphasizing name-based lookup.

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 'Use when looking for a specific station or browsing by keyword', providing clear context for when to invoke this tool. However, it does not mention 'when not to use' or name alternative tools, so it stops short of full exclusion 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 the annotations (readOnlyHint, idempotentHint), the description discloses the embedding model (BGE-base-en), windowing (500-char overlapping), and the 200K char truncation behavior. It also reveals that offsets are returned to support quote verification, which is a meaningful behavioral detail.

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

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

Four sentences, each contributing distinct value: purpose, use case, pairing, and technical constraints. The description is front-loaded with the primary action and stays focused without filler.

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

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

Given there is no output schema, the description supplies necessary return details: 'top-N passages with character offsets and similarity scores'. It also covers edge behavior (truncation) and the intended context, making it fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra: it restates 'text' as 'already pulled' content and 'query' examples, but these largely mirror the schema. It does not introduce new parameter semantics.

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 'Semantic search INSIDE a fetched record', giving a specific verb and resource. It distinguishes from sibling tools by contrasting with ask_pipeworx_grounded ('ground over the relevant passages instead of the whole document'), making the tool's narrow scope 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also gives a pairing workflow with ask_pipeworx_grounded, implying a two-step process and providing an alternative.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context: authentication requirements, subscription persistence limits, delivery channel behaviors (feed always on, email/sms options with verification and rate caps), and the return of the subscription id. It does not contradict annotations and provides operational detail beyond the structured fields.

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

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

The description is long but information-dense, with the main purpose and return value front-loaded. It covers multiple subscription types and delivery channels in a structured way, though some details (like delivery constraints) are repeated from the schema. Given the complexity, it is appropriately sized and not wasteful.

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 create-style tool with no output schema, the description covers the return value, authentication, core subscription types, and delivery options. It omits webhook delivery and two type variants (patent_grant, clinical_trial), but these are present in the schema. The description is sufficiently complete for an agent to use the tool correctly, though it could mention the remaining types and webhook for full coverage.

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 meaning through concrete examples (e.g., sec_8k items:['5.02'] = officer change, polymarket_edge topic:'fed', fred_series series_id:'UNRATE'). It also clarifies the feed delivery channel with a retrieval endpoint, which is not in the schema. However, it omits patent_grant and clinical_trial types that appear in the schema, so it doesn't fully compensate for all parameters.

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 'Create a proactive monitoring subscription to a live-data event stream', using a specific verb and resource. It clearly distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and it states the return value (the new subscription id).

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 prerequisite ('Requires a Pipeworx OAuth account') and states that anonymous/BYO cannot persist subscriptions. It also mentions the always-on feed and how to pull alerts (via recent_alerts or a GET endpoint), giving context for when this tool is appropriate. However, it does not explicitly name alternative tools for stopping or listing subscriptions, so it lacks explicit exclusions.

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 beyond annotations by explaining the return format (category-bucketed example questions with exact tool and argument shapes), the live catalog source, and the optional topic parameter behavior. Annotations already cover safety (read-only, idempotent), and the description adds valuable behavioral context 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 somewhat long but well-structured, front-loaded with user query examples and organized into clear behavioral details. Every sentence earns its place, though it could be tightened slightly without losing value.

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

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

Given the tool's onboarding role, the description fully covers what it returns (bucketed examples with tool+argument shapes), how to invoke it (with/without topic), and when to use it. The absence of an output schema is compensated by the explicit description of return contents.

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 schema description already explains the 'topic' parameter and the omit behavior. The description's mention of examples like 'finance', 'pharma', 'betting' is redundant with the schema's enum-like list, adding minimal new meaning. Baseline of 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 clearly states the tool's purpose: to return category-bucketed example questions for onboarding, with specific example queries. It distinguishes itself from siblings like discover_tools by positioning as the onboarding entry point for knowing what to ask.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', giving clear when-to-use context. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls short of a 5.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete nature ('the row is deactivated (not deleted) so its historical events stay available via recent_alerts'). These details explain authorization requirements and side effects, which the annotations 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 three sentences long, with the primary action first ('Cancel a subscription by id.'). Every sentence adds value: the first states the core purpose, the second explains a key constraint, and the third clarifies the behavior and its relation to historical data. 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?

For a simple single-parameter tool with annotations and no output schema, the description is complete. It covers what the tool does, the authorization model, the mutation behavior (soft-delete), and the impact on related data (recent_alerts). The annotations already cover idempotency and non-destructiveness, so the description need not repeat them.

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 schema already provides 100% coverage for the 'id' parameter, describing it as 'Subscription id (uuid) returned by subscribe.' The description adds the important constraint that the id must belong to the caller ('Ownership is enforced'), which gives additional semantic meaning to the parameter. This exceeds the baseline 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 opens with a clear verb-resource pairing: 'Cancel a subscription by id.' It explicitly names the action (cancel/unsubscribe), the resource (subscription), and the identifier. It also differentiates from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation and by noting ownership enforcement.

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 for when to use the tool: when you want to cancel a subscription. It does not explicitly mention alternatives or when not to use it, but the purpose is unambiguous enough that an agent can select it appropriately. The mention of ownership and soft-delete behavior further guides 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, and the description adds valuable behavioral details: the dual-path execution (SEC EDGAR fast path vs grounded pipeline), the returned verdict values, and pipeworx:// citations. 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?

The description is longer than typical but every sentence earns its place: trigger phrases, usage directive, dual-path logic, output summary, and efficiency claim. It is well-structured with a logical flow, not verbose rambling, and benefits from being thorough for a complex tool.

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

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

For a tool with 2 parameters, no output schema, and rich annotations, the description covers the essential contextual aspects: what it does, when to use, what it returns (verdicts, citation), and an efficiency note. It doesn't cover failure modes or edge cases, but overall it is complete enough to let an agent select and invoke it correctly.

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

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

Schema description coverage is 100%, with both parameters (`claim` and `tolerance_pct`) well-documented in the schema. The description adds only marginal semantic value beyond the schema, such as mentioning 'exact percent-delta math', but does not elaborate on the parameters themselves. 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 clearly identifies the tool as a natural-language claim verification tool with specific phrasing ('fact check', 'verify the claim that…'), and gives concrete examples. It distinguishes itself from siblings like 'ask_pipeworx' by focusing on checking truthfulness of claims rather than open-ended questions or 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?

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct', which is clear guidance. It also partitions use by claim type (financial vs other). However, it does not explicitly name alternative tools to avoid, though the claim-checking context is distinct enough from siblings like deep_research or compare_entities.

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