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 mark it read-only/open-world/idempotent, and the description adds meaningful behavioral context: it routes across verified sources, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with the primary directive and follows with usage triggers, examples, then alternatives. It is long but earned length; slight redundancy around 'news' and the list of trigger words keeps 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?

There is no output schema, but the description explicitly defines the return contract (structured answer + stable citation URIs), covers input style and examples, and provides enough guidance for an agent to call it correctly. It is complete for a router-style 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%: every parameter is documented and aliases are listed. The description contributes illustrative natural-language question examples, but no new parameter-level constraints or semantic details, so the high-coverage baseline of 3 applies.

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

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

States a specific verb+resource (routes a question to 5,798 tools and returns a structured answer with citations) and clearly supplies the factual data domain. It explicitly positions itself against ask_pipeworx_grounded and deep_research, so an agent can distinguish it from siblings.

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

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

Opens with 'PREFER OVER WEB SEARCH', gives explicit trigger phrases and question types, and names the exact alternatives for when to choose ask_pipeworx_grounded or deep_research. Includes concrete example queries, leaving little to inference.

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

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

Beyond the annotations, the description discloses the experimental nature, live candidate-routing behavior, current inactive-candidate status with a retirement date, and the fact that it is a fully working router with no fallback. This is exemplary transparency for an experimental tool variant.

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 tight sentences, each serving a distinct purpose: defining the variant, stating current status, giving usage guidance, and clarifying operational guarantees. The key information is front-loaded and 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 complex router with no output schema, the description adequately covers identity, current behavior, usage, and response-shape equivalence to ask_pipeworx. It is complete when the agent already understands ask_pipeworx, but a fully standalone description would benefit from a concrete example or a more explicit statement of what 'routing' means here.

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 all six parameters already documented as aliases of question, so the description does not need to repeat parameter details. The note that arguments match ask_pipeworx adds relational context, but the schema already provides the needed 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 identifies this as a beta variant of ask_pipeworx and as an identical universal router over the same 5,798 tools, so an agent can understand what it does at a high level. It distinguishes the beta variant from the stable ask_pipeworx by the routing improvements, though it assumes some prior knowledge of ask_pipeworx's function.

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 says to use it exactly like ask_pipeworx when you want the newest routing, which gives a concrete selection condition. It notes the comparison against the stable router, but it does not enumerate when to avoid the beta or prefer related siblings like ask_pipeworx_grounded.

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

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

Annotations already indicate read-only and idempotent behavior, and the description adds substantial value: exact success output shape, refusal output shape, refusal reasons, verbatim evidence, and the extra LLM call cost. There is no contradiction with 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 dense but every sentence earns its place: purpose, routing, behavior, output shape, refusal semantics, usage guidance, and cost trade-off. The core purpose is front-loaded before implementation details.

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

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

With no output schema, the description fully takes on the burden of describing return values, including success and refusal structures, and even enumerates refusal reasons. It also provides context about routing, source scale, and cost trade-offs. Nothing critical needed for correct invocation is missing.

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

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

Schema coverage is 100%, and the schema fully documents the question parameter plus all aliases. The description does not add parameter-level detail, but it does clarify the tool-level semantics of answering questions from source data. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific purpose: a hallucination-resistant answer mode for high-stakes reads, with the same routing as ask_pipeworx but grounded extraction. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing evidence, refusals, and no fact invention.

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 conditions are explicit: use when an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains listed. It also names the alternative ask_pipeworx and specifies when to prefer it due to the extra LLM call cost.

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?

Very rich behavioral disclosure beyond annotations: account/paid-plan requirements, parallel decomposition across 5,798 tools, exact return packet contents (evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[] scans, semantic excerpting, depth-mode mechanics, and latency expectations. No contradiction with annotations.

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

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

Dense and front-loaded with critical constraints (account required, paid tier) before the main function, and every sentence earns its place. However, it is a long run-on block with semicolons and parentheticals; light structural segmentation would improve scannability for an agent quickly parsing it.

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

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

Given no output schema, the description thoroughly explains return values, citation resolvability, gap handling, contradiction detection, and timing. It also covers auth, pricing, and the open/closed data boundary. An agent has everything needed to decide whether to call this tool and what to expect back.

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

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

Schema coverage is 100%, and the description adds meaning beyond what the schema provides. It explains what each depth mode actually does (quick=single hop, standard=gap recovery + contradictions, thorough=paid iterative hop + chasing leads), whereas the schema only lists enum values. This materially helps an agent choose correctly.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the alternative for single lookups, so an agent can tell it apart from siblings.

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

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

The description gives explicit when-to-use guidance for broad/multi-part questions over structured data and says 'For a single lookup use ask_pipeworx instead.' It even handles the auth conditional: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' Exclusion conditions and alternatives are fully explicit.

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

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

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

The description adds substantial behavioral context beyond the readOnly/openWorld/idempotent annotations: multi-source fan-out, soft-fail behavior for the USPTO API, expected empty FDA sections for non-biologic companies, resolved:false handling for private companies, and the meaning of sources_used/sources_failed. 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 information-dense but excessively long and delivered as one continuous wall of text with many redundant query examples and parenthetical asides. Front-loading is decent, but it would be more effective with bullets or tighter organization.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly: it enumerates output sections, example URIs, failure modes, and expected empty data conditions. An agent has enough context to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that type is interchangeable, and explaining how names resolve via SEC EDGAR. This goes beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: produce a full cross-source profile of a US public company in one call, with example queries like 'company profile for Microsoft'. It contrasts with chained single-pack SEC/XBRL/news lookups, but it does not name or explicitly differentiate from sibling tools such as 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?

It gives explicit guidance: prefer this tool over chaining single-pack lookups when the user asks for a holistic view, and it covers acceptable input forms (ticker, CIK, company name). It does not state specific exclusions or alternative tools for comparison or entity-resolution tasks, so it stops short of a full when-not guide.

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?

Beyond annotations (all false), the description discloses important behavior: it returns a claim_token for anonymous filing, subsequent calls can check resolution status via claim_token, it is rate-limited to 5 per identifier per day, and it is free. It stops short of explicitly stating that each call creates a new write/side effect, but the 'Send' verb and claim_token workflow make that clear. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: purpose, use cases, exclusions, content guidance, claim_token flow, team review cadence, rate limit, and cost. It is front-loaded with the core action and structured logically, making it easy to scan.

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

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

The description covers all key aspects needed to invoke the tool correctly: when to use, what to avoid, how to format feedback, how to retrieve resolution via claim_token, rate limits, and cost. No output schema exists, but the description explains the claim_token response, which is sufficient for this side-effecting feedback tool.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema: it explains the claim_token workflow (pass it back alone to read resolution), clarifies the intent of each feedback 'type', and gives message length/format guidance. This goes well beyond the raw parameter descriptions.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates specific use cases (bug, feature/data_gap, praise), making it easy to distinguish from all sibling tools, none of which are feedback-related.

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 tells when to use the tool (bug, feature, data_gap, praise) and when NOT to use it, stating that issues with other MCP servers should be filed elsewhere. It also gives actionable guidance on how to describe the issue (in terms of Pipeworx tools/packs, not pasting user prompts).

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?

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive, lowering the burden. The description goes far beyond by detailing the token-overlap matcher, both modes running identically, the meaning of each compatibility code, the gross-vs-net fee caveat, and the behavior of skipped/unclassified legs. This is exemplary behavioral disclosure.

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

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

The description is front-loaded with the core purpose and modes, and nearly every sentence adds operational value. It is quite long, densely packing caveats and field definitions; while none of it is filler, the sheer volume risks overwhelming an agent that only needs a quick invocation. It earns a 4 rather than a 5 because it is more encyclopedic than concise.

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

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

There is no output schema, so the description must carry the full burden of explaining return values. It covers leg-by-leg prices, top_spreads_pp, safety fields, compatibility codes, temporal alignment semantics, fee disclosures, and skipped-leg counters. For a tool of this complexity, nothing essential 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, but the description adds substantial meaning: it explains that `topic` auto-fetches matching events, that the explicit parameters override the mapped sides, and that both modes run the same matcher. This transforms a bare list of three parameters into a clear decision procedure for invoking the tool.

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

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

The opening sentence states a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly differentiates the tool from siblings like polymarket_arbitrage and polymarket_edges by naming both venues and the shared-question constraint. The two modes and the response structure reinforce what the tool produces.

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 clear context on when to use the tool and how to choose between the two modes: topic shortcuts for pre-mapped macros and explicit ticker+slug for custom pairings. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' However, it does not explicitly contrast the tool against alternative siblings, so it stops short of full when/not 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 (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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses internal cascading lookups, graceful degradation when GLEIF or OpenFIGI is unavailable, ambiguity handling via figi_candidates, and explicit reporting of unresolved identifiers. These are behavioral traits an agent could not infer 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 long but well-structured with SUPPORTED TYPES and parenthetical examples. Nearly every sentence carries operational detail, and the purpose and usage guidance are front-loaded, though some phrases could be trimmed for tighter reading.

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 covers inputs, supported entity types, return behaviors (figi_candidates, unresolved), and failure degradation. The only minor gap is a precise response shape, but the detailed behavioral description makes the tool usable without one.

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 critical semantics: value must be the ENTITY NAME ONLY, bond issuer names must be passed exactly as printed, and trailing security-class words will fail to match. It also explains that ambiguous name matches return figi_candidates rather than asserting a single result.

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 query patterns ('What's the ticker for…', 'find the CIK for…') and states the core function: resolving a user-spoken NAME to canonical/official identifiers other tools require. It distinguishes resolve_entity from sibling tools like entity_profile and compare_entities by positioning it as the FIRST step whenever you have a name but need an 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 explicitly instructs 'Use FIRST whenever you have a name but need an ID' and details the two supported types with input examples. It does not name sibling tools as alternatives or state explicit exclusion conditions, but the context for when to use it is clear and actionable.

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

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

Annotations already 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 readOnly/openWorld/idempotent/non-destructive; the description adds critical behavioral detail: could_not_verify means the check did not happen and must not be interpreted as evidence, unsupported means no source exists, and describes the two execution paths (SEC EDGAR + XBRL fast path vs grounded pipeline). No contradiction with annotations.

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

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

The description is longer than average but well-structured: front-loaded with trigger phrases and purpose, then pipeline routing, verdict definitions, error semantics, and a note about replacing sequential calls. Every sentence conveys necessary operational detail, justifying its length without being verbose.

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?

Even without an output schema, the description enumerates all verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), the error field structure (verification_error{stage,detail}), citation format (pipeworx://), and reasoning. It covers the full behavior contract including failure modes and caller responsibilities, making it complete for a complex tool.

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

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

Schema provides 100% parameter descriptions, so baseline is 3. The description adds actionable guidance on tolerance_pct, including recommended 1–2 for hallucination detection where any material error must be refuted, and explains that default is implied by wording with a 5% cap, which enhances meaning beyond the schema.

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

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

Description explicitly states the tool performs natural-language claim verification against authoritative sources, with a specific verb 'verify' and resource 'claims'. It clearly distinguishes from sibling research/entity tools by focusing on fact-checking and mentions it replaces multi-step pipelines like NL parsing → entity resolution → data lookup → 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing rules for company-financial claims vs any other factual claim. Includes exclusion semantics for could_not_verify/unsupported, telling callers when not to treat as evidence, and clarifies the tool replaces 4–6 sequential calls.

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