Irail

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds behavioral details about default model, optional API key for Anthropic, probe scope, and return structure. No contradiction with annotations.

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

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

Description is a single paragraph of 4-5 sentences, front-loaded with the primary action and purpose. Every sentence adds value: purpose, default model, key usage, return format, use cases. 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?

With 4 parameters, 100% schema coverage, no output schema, the description adequately covers return shape and overall behavior. It mentions per-model result fields and combined view, which is sufficient for the tool's complexity.

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

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

Schema coverage is 100%, so parameter descriptions already exist. The tool description adds contextual usage (e.g., 'Default model is Workers AI...', 'BYO key'), but does not significantly enhance meaning beyond the schema. 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?

Description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on a single entity and providing a visibility metric.

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?

Description gives explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to use _apiKey for Anthropic. However, it does not explicitly state when not to use the tool or provide alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context about routing, filling arguments, returning pipeworx:// citation URIs, and being a fast default; it also subtly implies limitations by recommending grounded for hallucination-resistant answers.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and organized into use cases, examples, and step-up alternatives. While long, every sentence provides actionable guidance without redundancy, 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 complexity as a router, the description covers purpose, usage, alternatives, return format (structured answer with citations), and limitations. Without an output schema, it sufficiently explains what the agent can expect from the 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?

Input schema covers all 6 parameters (aliases) with descriptions, achieving 100% coverage, so baseline is 3. The description adds semantic value with concrete examples ('current US unemployment rate', 'Apple's latest 10-K') and trigger phrases, enriching comprehension of the 'question' parameter.

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

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

The description explicitly states the tool routes questions to 5,462 tools across 1419 verified sources and returns structured answers with citation URIs. It clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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 provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also gives step-up alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions.

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 valuable context beyond these: that it is a live experimental router with candidates toggled on/off, currently matches the stable router exactly, and has no fallback (it is a full working router). This explains its behavior 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 a single paragraph of three sentences that conveys all essential context (beta status, identity, current state, usage guidance, and fallback behavior). It is fairly dense but no information feels wasted, though it could be slightly tighter without losing key 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?

The description sufficiently covers the tool's experimental nature, current equivalence to the stable router, and the fact that it is fully operational. It does not describe return values, but there is no output schema and the response shape is stated as identical to ask_pipeworx, which is acceptable given prior context.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for question. The description only mentions 'same arguments' without adding any new semantic detail, so it meets the baseline but does not elevate it.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router, and explicitly distinguishes it from the stable sibling by stating it has 'candidate routing improvements' and is 'the experimental edge.' It also specifies the identical scope (5,462 tools, same arguments, same response shape), making the purpose unambiguous.

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

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

The description gives explicit usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the comparison context and the current equivalence to the stable router, effectively stating when to choose this beta over ask_pipeworx.

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 and idempotentHint annotations, the description discloses that it performs multi-step tool routing and extraction, returns structured evidence with verbatim quotes, and explicitly refuses with specific refusal_reason codes when data doesn't answer. It also reveals the extra LLM call overhead. 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 despite covering purpose, mechanism, return format, use cases, and cost. Each sentence adds distinct value, from 'hallucination-resistant' to the refusal_reason enum. It is front-loaded with the core purpose and ends with actionable 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?

Given the tool's complexity (routing across thousands of sources, grounding, refusals), the description fully explains behavior, outputs, and limitations. It includes both success and refusal response structures, making it self-sufficient without an output schema.

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

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

The input schema already provides comprehensive descriptions for all six parameters, all aliases for 'question'. The description adds no additional parameter semantics beyond the schema, so it relies on the schema's 100% coverage. No further explanation needed.

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 this is a hallucination-resistant answer mode for high-stakes reads, and explains it routes through the same tool selection as ask_pipeworx but extracts answers only from tool results. This distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta by emphasizing grounded evidence-based answers.

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 instructs to use whenever an answer will be quoted, cited, or acted on, and to avoid inventing facts in domains like finance, law, medicine, and public statements. It also notes the extra LLM call cost and advises preferring ask_pipeworx for casual lookups, naming the alternative directly.

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

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

Annotations mark it as readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: resolution paths, fan-out examples, response shapes, safety mechanisms (low-confidence resolution blocking, closed market handling), wide-spread liquidity warnings, and resolution-rule risk parsing. No contradictions with annotations.

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

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

The description is long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds necessary detail given the tool's complexity. Could be slightly more concise but earns its length.

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?

No output schema exists, yet the description fully covers response structure, resolver contract, parent event extraction, news fallbacks, safety guards, and cancellation rule parsing. It anticipates agent needs for understanding market-match confidence and edge calculations. Exceptionally complete.

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

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

Input schema covers 100% of parameters. The description adds substantial meaning: explains the 'market' parameter accepts slug, URL, or question text; describes 'depth' (quick vs thorough) with default; details 'include_raw' with size implications. This goes beyond the schema definitions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output components (evidence packet, market-vs-model comparison). It distinguishes from sibling tools by focusing on Polymarket betting research.

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

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

Explicit usage examples are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. While it doesn't explicitly state when not to use it, the context is clear enough for an agent to infer appropriate scenarios.

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 indicate readOnly, openWorld, idempotent. Description adds that company pulls latest 10-K from SEC EDGAR/XBRL with correct fiscal year handling, drug pulls FAERS data, results sorted by primary metric. No contradictions.

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

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

Description is a single well-structured paragraph with examples, guidance, and details. Front-loaded with core purpose; every sentence adds 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 complexity (two types, multiple data sources, sorting), the description covers purpose, data sources, sorting, and output. Lacks explicit mention of return format details like metric name for sorting.

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

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

Schema coverage is 100%. Description adds meaning by explaining type enum values and values array constraints (max 5, min 2, examples). This goes beyond schema but is not necessary.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with specific verb phrases like 'Compare X and Y'. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

The description explicitly says to prefer this tool over sequential single-pack lookups for comparisons, and explains when to use company vs drug. However, it does not explicitly mention alternatives for single-entity lookups.

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, but the description adds substantial behavioral context: parallel decomposition across 5,462 tools, findings packet structure (verbatim evidence, confidence, source, fetched_at, citations), gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, account/paid-plan requirements, 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?

The description is long but densely informative, front-loading the most critical facts (account required, free tier, alternative tool). It covers many operational details in a structured flow, though slightly verbose. Every sentence contributes useful context for such a complex tool.

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

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

For a complex tool with no output schema, the description is remarkably complete: it covers prerequisites, suitable use cases, limitations on current news topics, expected output (findings packet, gaps, contradictions, citations), latency, and failure modes (empty gaps). The agent is well-equipped to decide when and how to invoke this tool.

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

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

Schema coverage is 100%, with both 'question' and 'depth' documented. The description adds value by explaining depth levels more concretely ('standard re-angles unanswered gaps', 'thorough is paid; adds a full iterative hop') and clarifies that 'question' accepts broad/multi-part natural language. This goes beyond schema basics without being redundant.

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

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

The description clearly states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and explicitly contrasts with open-web search. It also distinguishes itself from sibling tools by scope ('NOT open-web search') and use case, making it immediately identifiable.

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 guidance: 'Best for broad/multi-part questions over structured data' and explicit alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also notes account tier requirements, leaving no ambiguity about appropriate contexts.

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?

Description adds detail beyond annotations: output includes full schemas with curated examples, ready to call directly. No contradictions with annotations. Explains what the return looks like.

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

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

Two concise sentences. First sentence states purpose, second explains output and usage. Front-loaded 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?

Given complexity (many siblings, 6 parameters, no output schema), description provides complete context: return structure, example domains, and positioning as discovery entry point.

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

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

Schema coverage is 100%; description does not add new semantics about parameters beyond listing example query strings. 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?

Description clearly states the tool finds tools by describing data or task, lists many domains, and explains what it returns (top-N tools with schemas). Distinguishes itself from siblings by positioning as a first-call discovery tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. Provides clear context and implicit 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, idempotent, and non-destructive. The description adds significant behavioral context: parallel fan-out across multiple sources, soft-failure of patents API, fallback for news, and specific return fields. However, it omits details like rate limits or error handling for API failures.

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

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

The description is detailed but front-loaded with examples and purpose. Every sentence adds information, but it could be slightly more concise by omitting some inline examples (e.g., the list of ticker examples in parentheses). Structure is logical: examples, purpose, usage hint, data sources, input format.

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

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

Given the complexity of the tool (multi-source aggregation) and the absence of an output schema, the description thoroughly explains what each returned field contains, along with caveats (patents sunset, news fallback). This provides complete guidance for an agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the 'type' parameter is currently restricted to 'company' (in schema) and that 'value' must be a ticker or zero-padded CIK, with a note that names are not supported. This extra context justifies a score above 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 the tool provides a holistic cross-source profile of a US public company in one parallel call, with specific examples and a list of returned data types. It distinguishes itself from chaining multiple single-purpose tools and implicitly contrasts with sibling tools like resolve_entity for name resolution.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clearly states input constraints (ticker or CIK, not names) and directs to use resolve_entity if only a name is available.

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 destructiveHint=true and idempotentHint=true. The description adds behavioral context by clarifying the deletion is for clearing sensitive or stale data, 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?

Two short sentences with no fluff. Every sentence adds value: first states the action, second provides usage context and sibling references.

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 deletion tool with one parameter, no output schema, and adequate annotations, the description fully covers the necessary context—what, when, and how to use.

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

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

Schema coverage is 100% with a single parameter 'key' adequately described. The description does not add extra meaning to the parameter, 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 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), and distinguishes from sibling tools 'remember' and 'recall' which are opposite actions.

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: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions alternatives by saying 'Pair with remember and recall.'

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?

Describes non-destructive, idempotent fetch-and-extract behavior, aligning with annotations (readOnlyHint, idempotentHint, openWorldHint). No contradictions; adds detail about standard output format.

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

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

Single efficient paragraph front-loads purpose and ends with practical output note. 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?

No output schema, but description fully explains output format (text blob) and deployment location. Simple tool with complete context.

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?

Both parameters (url, max_links) have schema descriptions and the tool description adds default (25) and max (50) for max_links, enhancing schema coverage.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying extraction of title/description/key links and output format. It distinguishes itself from siblings by focusing on a specific, unique functionality (AI crawler indexing file).

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 lists three use cases: getting a client's site indexed, drafting for your own project, or auditing competitor AI visibility. Could mention when not to use, but context is sufficient.

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, so the description does not need to repeat safety traits. It adds value by listing returned fields (title, summary, type, link, last-updated time) and mentioning the network scope, but does not disclose potential behavioral nuances like rate limits or data freshness.

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 (one sentence plus an example) and front-loads the core purpose. Every sentence is informative, though the example is slightly redundant given the schema's examples. Still, it is well-structured and avoids verbosity.

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, no output schema, comprehensive annotations), the description provides sufficient context: it names the network, lists output fields, and shows a usage example. It could elaborate on output format details, but the listed fields suffice for an agent to understand what to expect.

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% (the only parameter 'limit' is fully described with range 1-50 and default 15). The description does not mention the parameter, so it adds no additional semantic value beyond what the schema already provides. Baseline score 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 it returns 'current disturbances, incidents, and planned works' on the Belgian rail network. It lists output fields (title, summary, type, link, last-updated time) and provides a usage example. This differentiates it from sibling tools like irail_journey, irail_liveboard, and irail_train, which focus on different aspects of rail data.

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 the tool is for checking disruptions via phrases like 'current disturbances' and 'affecting Belgian train service,' and includes an example call. However, it does not explicitly state when to use this tool over alternatives or provide when-not-to-use guidance, leaving usage context implied rather than 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 and destructiveHint=false, establishing safety. The description adds behavioral detail: live delays, platforms per leg, and time interpretation in Belgian local time. This goes beyond annotations but does not discuss rate limits or authentication, though those are not critical for a read-only tool.

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

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

The description is three sentences with an example, no redundant words. The first sentence front-loads core purpose and outputs. Every sentence adds value: purpose, usage examples, parameter format hint, and a code example.

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 5 parameters (2 required) and no output schema, the description covers tool purpose, major outputs, parameter usage, and timezone. Missing details include default limit (4) and result ordering, but these are partially addressed in the schema. It is mostly complete for a straightforward read-only 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?

With 100% schema coverage, baseline is 3. The description adds meaning beyond schema by clarifying that depart_at/arrive_by accept ISO datetime or time formats and are interpreted in Belgian local time. It also provides a concrete example of required parameters, enhancing understanding of the from/to naming convention.

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 plans a train journey between two Belgian stations via SNCB/NMBS, listing specific outputs like legs, transfers, delays, platforms. It includes example questions that make the purpose unmistakable, and the verb 'plan' combined with 'between two Belgian stations' distinguishes it from sibling tools like irail_liveboard (station departures) or irail_disturbances.

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 example queries showing when to use ('next train from Brussels to Antwerp'), but does not explicitly state when not to use this tool or mention alternatives like irail_liveboard for single-station departures. The context is clear but lacks exclusionary 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 indicate read-only, open-world, and idempotent behavior. The description adds value by detailing station name flexibility (exonyms, fuzzy input) and the example usage pattern, but does not mention data freshness or rate limits.

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

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

Two sentences plus an example convey all necessary information without redundancy. The key purpose and usage hints are 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 3-parameter tool with no output schema, the description covers all parameters, expected output fields, and station name flexibility. No missing context.

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

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

Schema has 100% coverage. The description adds meaning by clarifying station name accepts exonyms and fuzzy input, and implicitly notes the default type is departure. This goes beyond the schema's simple enum and string 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 it is a live departures board for Belgian train stations and lists specific output fields. It is clear but does not explicitly differentiate from sibling tools like irail_journey or irail_disturbances.

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 mentions setting type to 'arrival' for arrivals board and provides station name examples, but does not provide when-to-use vs alternatives or when not to use.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral details: it returns per-stop delay in minutes, platforms, current delay, and live position. It also specifies acceptable ID formats. 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 three sentences long, front-loaded with the core purpose, then detailed outputs, and ends with a concrete example. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 parameters, no output schema, but rich return data), the description covers all essential information: what it returns, how to call it with different ID formats, and the source of train numbers. No gaps remain.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema. It explains acceptable formats for the id parameter (e.g., 'IC 1832', 'IC1832', 'BE.NMBS.IC1832') and provides an example call. For the date parameter, it clarifies the default behavior (today Belgian time).

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

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

The description clearly states it tracks one Belgian train by number, providing detailed stop times, delays, platforms, and live position. It distinguishes from siblings by mentioning train numbers come from irail_liveboard or irail_journey, making the tool's specific purpose unambiguous.

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

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

The description gives clear context for when to use: to check if a Belgian train is delayed. It explains that train numbers are obtained from irail_liveboard or irail_journey, guiding the agent to first use those tools. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling list provides context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms read-only nature but adds little beyond annotations; it mentions return fields and default active subscriptions, which is adequate but not exceptional.

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

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

Two concise sentences: first states purpose and output, second gives usage advice. No unnecessary words.

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

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

Given no output schema, the description lists all return fields. It covers the parameter behavior (active by default) and usage scenarios. Complete for a simple list tool.

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

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

Schema coverage is 100% for the single optional parameter 'include_inactive'. The description does not add new semantic meaning beyond the schema's description, 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 it lists the caller's active subscriptions and lists the return fields (id, type, params, etc.). It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for 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 are all false and provide no behavioral hints, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and how feedback is processed ('The team reads digests daily and signal directly affects roadmap'). This goes well beyond what any annotation could convey.

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

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

The description is long but every sentence earns its place. It starts with the core purpose in the first sentence, then flows into usage triggers, exclusions, content rules, rate limit, and quota impact. There is no fluff or repetition; each detail is necessary for correct use of a feedback tool with these caveats.

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

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

The tool has no output schema, but the description sets expectations for what happens after submission ('team reads digests daily' and no instant response is implied). It also covers all critical context: what the tool does, when to use it, what it cannot fix, how to phrase feedback, and behavioral limits. For a feedback submission tool, this is 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 description coverage is 100%, so the schema already explains each parameter thoroughly. The description adds valuable semantics: it maps real-world situations to the `type` enum values and instructs on how to write the `message` (specific to Pipeworx tools/packs, no prompting). This extra guidance elevates the description above the schema 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then lists concrete use cases (bug, feature/data_gap, praise), making it unmistakably distinct from siblings like ask_pipeworx (which answers questions) or discover_tools (which lists 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?

It explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides clear exclusions: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' Guidance on how to phrase feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') further clarifies 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, and non-destructive hints. The description adds valuable behavioral details: data is self-aggregating from analytics, no PII, and cached with window-dependent durations. This goes well beyond what annotations provide.

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

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

The description is compact (four sentences plus a bullet list), with the main function stated first. Every sentence adds value, and the structure is clear and 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 tool with one parameter and no output schema, the description covers return content, use cases, data source, privacy, and caching. Annotations handle safety. No gaps remain.

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

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

Schema coverage is 100% with enum description. The description adds semantic guidance on window choice ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which helps the agent select the right value beyond the schema's basic definition.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It includes explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case) which define its purpose precisely and 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?

The description provides three clear usage scenarios, but does not explicitly mention when not to use this tool or alternatives. The context from sibling names (e.g., discover_tools, ask_pipeworx) implies alternatives, but the description itself does not draw comparisons.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details internal checks: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against CLOB depth, and how signals are generated. No contradictions with annotations.

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

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

The description is verbose (several paragraphs) but well-structured with clear sections. Some details could be streamlined, but the structure aids readability. Not overly concise but earns its length.

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?

Completely covers all aspects: two modes, input examples, output structure (opportunities[], partition_check, fill check), and behavioral constraints. Despite no output schema, the description ensures an agent can understand return values and trade decisions.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explaining usage context (event vs topic), accepting full URLs, and clarifying that topic searches across related events. Slightly above baseline due to extra context.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates between event and topic modes, and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Excellent usage guidance: recommends event mode for specific markets and topic for cross-event scanning, provides example inputs, explains when not to trade (if realizable_edge_pp ≤ 0), and references a sibling tool for custom sizing.

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

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

Annotations indicate readOnly, openWorld, idempotent, not destructive. The description adds extensive detail: caching (1h KV level), diagnostics for empty segments, and edge metrics like 24h-move warning. There is 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 very long and dense, containing valuable information but could be more structured (e.g., using bullet points or breaking into sections). It front-loads the main purpose but drifts into detailed model explanations. Still every sentence adds value, but conciseness is suboptimal.

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

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

Given the tool has no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and the meaning of each field. It also covers parameter effects, edge metrics, and model details, making it fully self-contained for an agent.

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

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

Schema coverage is 100% with each parameter having a description. The description adds extra context beyond schema, such as tradeable-edge knobs (max_spread_pp, min_liquidity), default values, and usage notes for complex parameters like min_partition_leg_kelly.

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

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

The description explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear use case 'what should I bet on today'. It distinguishes from siblings by describing unique models and output segmentation.

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

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

The description provides context for when to use ('what should I bet on today') and mentions that Fed bets are excluded from ranking, indicating a limitation. It also details tradeable-edge knobs for filtering, but does not explicitly compare to sibling tools like polymarket_arbitrage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds rich behavioral details: data source (daily snapshots), how decay is computed (on |edge_pp_net|, signed), snapshot gaps, and output structure (tracked, expired, snapshot_dates). No contradictions.

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

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

The description is well-structured, starting with the core question, then detailing output fields in a readable format. It's somewhat lengthy but every sentence adds value. Minor redundancy could be trimmed.

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 (tracked, expired, snapshot_dates with field descriptions) and covers limitations (60-day TTL, daily closes, gaps). For a complex tool, this provides comprehensive context.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window). The description adds context like default values (14 for days, '1wk' for window) and clamping (2-30), but this is already implied in schema. Baseline 3 is appropriate as description adds minimal extra 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 tool tracks edge persistence and decay over time, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series and decay, not just current edges.

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 explains when to use this tool (when edge age and decay matter) and provides context like 'a 3-week-old wide edge is different'. It also mentions limits (60-day TTL, gaps in snapshots). However, it doesn't explicitly contrast with alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: it describes walking the ladder, returning verdicts (clean|degraded|cannot_fill), identifying thin legs, and highlighting forced directional risk. 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 and well-structured, with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and front-loading of purpose. Every sentence adds value. However, it is relatively long; a more concise version could exist without losing critical details, hence a 4 rather than 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?

Given the tool's complexity (dual mode, financial risk implications) and lack of output schema, the description is highly complete. It enumerates all return fields for both modes, explains the risk of partial basket fills, and ties to sibling tools. No additional information is needed for an 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 description coverage is 100%, so baseline is 3. The description adds value by clarifying that one of `market` or `event` is required, explaining size_usd interpretation (spend vs proceeds for single-market, shares per leg for basket), and noting defaults and clamps. This goes beyond the schema alone, earning a 4.

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 does a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two distinct modes (single-market and basket). It differentiates from sibling tools by explicitly stating when to use this tool before acting on signals from polymarket_arbitrage or polymarket_edges, ensuring no ambiguity.

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 usage guidelines: use this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It explains the rationale (theoretical overround not capturable on thin books, partial fills causing directional risk), which helps the agent decide when to invoke the tool.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses critical behavioral details: the two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. It explains when spreads are invalid (e.g., non-equivalent bet shapes, temporal misalignment), which is essential for correct interpretation.

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: purpose, then modes, then response, then safety fields, then caveats. It is front-loaded with the core concept. However, it is somewhat verbose; could be tightened without losing information. The length is justified by the complexity but is not maximally 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?

Given the lack of an output schema, the description thoroughly explains return values (leg prices, spreads, compatibility flags) and fields like temporal_alignment and skipped counters. It covers all necessary aspects: modes, parameter usage, safety checks, and limitations. There are no obvious gaps for an AI agent to invoke the tool correctly.

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

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

The description adds meaning beyond the input schema by explaining the two modes and how explicit parameters override topic mappings. It also provides context for the interplay between parameters (e.g., topic vs. explicit tickers). The schema already covers all parameters with descriptions, so the baselines are met.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes this from single-venue arbitrage tools like polymarket_arbitrage, making its unique value evident. The phrasing 'Cross-venue spread' is precise and actionable.

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 explains two modes (topic shortcuts and explicit pairings) and provides guidance on when to use each. It also includes a caution that most pre-mapped topics currently return compatibility_warnings, advising users not to assume they are tradeable. However, it does not explicitly compare with sibling tools like polymarket_arbitrage to guide choice.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining scoping ('Scoped to your identifier') and the behavior when key is omitted (list all keys). No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the action. Every sentence adds meaningful information (purpose, usage guidance, scoping, pairing). No unnecessary words, though the structure could be slightly tighter.

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 (1 optional parameter, no output schema, annotations present), the description covers purpose, usage, scope, and relationship with siblings. It does not explain return format or limits, but these are not critical due to the tool's nature and existing annotations.

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

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

Schema coverage is 100% and the schema already describes the parameter ('Memory key to retrieve (omit to list all keys)'). The description repeats this but adds context about pairing with 'remember' for saving. This adds minor value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys when omitted. It uses specific verbs ('retrieve' and 'list') and identifies the resource ('value saved via remember'). It also distinguishes from siblings like 'remember' (save) and 'forget' (delete).

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 when to use the tool: 'to look up context the agent stored earlier' and 'without re-deriving it from scratch.' It implies usage context (e.g., retrieving user target ticker, address, notes) but does not explicitly state when not to use it or list alternatives beyond the paired 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?

The description discloses that mark_read mutates feed state (flags events as read), but the annotations include readOnlyHint=true, indicating no state modification. This is a direct contradiction, forcing a score of 1 per rubric.

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 dense with information and front-loaded with purpose. Every sentence adds value, though could be slightly more streamlined. No waste.

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 explains return fields and parameter behavior well. Also mentions polling and alternative access. Missing pagination details but overall sufficient.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning by explaining the purpose of mark_read, type filter, ISO timestamp format for since, and limit range, plus describes return fields.

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 pulls fired events from subscription feed, returning recent alerts with specific fields. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on retrieval rather than management.

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

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

Provides guidance on when to use the tool vs. alternative access via GET request, and mentions polling suitability. Does not explicitly state when not to use, but gives useful context with the alternative endpoint.

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. Description adds significant behavioral detail: single parallel call, fan-out to multiple sources, fallback logic (GDELT→GNews on rate limit/5xx), USPTO soft-fail until May 2025, and return structure (grouped changes, total count, citation URIs). 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?

Single paragraph, front-loaded with example queries. Every sentence adds essential information (sources, fallback, parameter examples, relationship to sibling). No wasted words; perfect density for a complex tool.

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

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

Given the tool's complexity (multiple data sources, fallback logic, multiple input formats, no output schema), the description covers all necessary aspects: input constraints, source behavior, return structure. Even mentions soft-fail and sunset dates. Fully prepares an agent for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by giving concrete examples for 'since' (ISO date and relative shorthand like '7d', '30d'), recommending typical monitoring window ('30d' or '1m'), clarifying 'value' accepts ticker or zero-padded CIK, and noting 'type' is only company. These extras elevate clarity beyond schema.

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

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

Description clearly states it provides a change feed for a company over a time window, listing sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing from sibling entity_profile for static profiles. Specific verb 'change feed' along with example queries ('What's new with X') make purpose immediately 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 gives use cases ('What's new with X') and when-not-to-use (entity_profile for static profile). Also describes fallback behavior between GDELT and GNews, and soft-fail for USPTO. Provides clear context for invocation.

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

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

Adds value beyond annotations by specifying scoping by identifier, persistence differences for authenticated vs. anonymous sessions, and storage format (key-value). No contradictions with annotations.

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

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

The description is concise, front-loaded with the main action, and uses efficient sentences without redundancy. Every sentence adds 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 simple two-parameter tool with no output schema, the description covers all needed context: purpose, usage, persistence details, and related tools. Completeness is high.

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

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

Schema has 100% coverage with descriptions for key and value. The description adds examples of key patterns (e.g., 'target_ticker') that enhance understanding, justifying a score above the baseline of 3.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, using specific verbs and resource framing. It distinguishes from sibling tools like recall and forget by explicitly mentioning pairing with them.

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 to use when discovering something worth carrying forward, and pairs with recall/forget for retrieval/deletion. Provides clear context for when to use vs. alternatives.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful behavioral details: internal cascading through multiple endpoints, auto-disambiguation for company names, and return specifics (ticker, CIK, RxCUI, 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 somewhat long but well-structured: it leads with example queries, then a concise core statement, followed by a breakdown of supported types. Every sentence serves a purpose, and the front-loading makes it easy to grasp quickly.

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

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

There is no output schema, so the description compensates by detailing exactly what each type returns (ticker + CIK + company_name; RxCUI + ingredient + brand) and how it fits with other tools. It also notes that each call replaces 2-3 manual lookups, giving useful context. Minor gaps like error handling are not critical.

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

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

Schema already covers both parameters with descriptions (100% coverage). The description goes beyond by providing concrete examples for each type (AAPL, 0000320193, 'ozempic') and clarifying that company input can be a ticker, CIK, or name with auto-disambiguation, adding 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 clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It includes specific verbs ('resolve', 'find', 'look up') and distinguishes from siblings by saying 'Use FIRST 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?

Provides explicit trigger conditions: 'Use FIRST whenever you have a name but need an ID' and example user queries. It implies when not to use (when you already have an ID) but does not explicitly list exclusions or alternative tools. Still, it clearly guides the agent on when to invoke this tool.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds internal mechanics (probes each entity with ai_visibility_check, ranks by score) and return structure (score, confidence, signal density). 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?

The description is two sentences, front-loaded with purpose. The second sentence is slightly long but contains valuable context. 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?

Given no output schema and annotations covering safety, the description adequately explains tool function, internal process, return format, and example use. Missing details on error handling are acceptable for this complexity level.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds marginal value by explaining the first entity is the 'subject' and rest are competitors, but overall does not significantly augment schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tool ai_visibility_check (single entity) and compare_entities.

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 specific use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly mention when not to use or alternatives to this tool.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement on a new version can take 5-30 seconds, and sources_failed will list if it times out. 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?

The description is a single, well-structured paragraph that front-loads the purpose and then details return values and behavior. Every sentence adds value, though it is slightly long. Could be shortened but still 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?

The description comprehensively covers the output format (summary block with fields, per-advisory detail, links, alternative versions) and error handling (partial failures with sources_failed). No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: scoped packages (e.g., @types/node) are accepted, and version defaults to the latest published version when omitted. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for adding an npm package, covering license, advisories, version history, bundle size, and tree-shake support. It explicitly limits scope to NPM ecosystem in v1, distinguishing from other tools that handle different ecosystems.

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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and clarifies that other ecosystems fall under different tools ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds technical details: embedding model (BGE-base-en), similarity measure (cosine), chunking (500-char overlapping windows), and truncation (200K char cap with flagging). This provides valuable behavioral context 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?

Single, well-structured paragraph. Front-loaded with the core purpose, followed by use case, pairing, then technical details. Every sentence adds value without redundancy. 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?

Covers all important aspects: purpose, when to use, how to use (text+query), technical details (model, chunking, limits), and what is returned (passages with offsets and scores). Missing error handling or empty result behavior, but for a search tool this is adequate. No output schema, but description fills the gap.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. Description adds meaningful usage context: 'Pass the text you already pulled', 'natural-language query', 'get back the top-N passages with character offsets and similarity scores'. The query parameter includes examples, and limit behavior is implied. Exceeds baseline of 3 by adding examples and explanation of return format.

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 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article, long tool result). It distinguishes from general search by specifying it works on already-fetched text and explicitly pairs with ask_pipeworx_grounded, differentiating from siblings.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. While it doesn't explicitly say when not to use, the pairing provides implicit guidance. Could be improved with direct 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 indicate a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description elaborates on OAuth necessity, SMS cap, webhook auto-disable, and signing secret—adding useful behavioral context beyond annotations, though it could mention idempotency explicitly.

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

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

The description is detailed yet well-structured; it opens with the primary action, then systematically covers types and delivery options. Every sentence adds value, though the length could be trimmed by grouping some examples.

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 (3 parameters, nested objects, no output schema), the description is comprehensive: it covers authentication, type-specific params, delivery channels, constraints (SMS cap, webhook auto-disable), and expected return value. No output schema is needed as the return is clearly stated.

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

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

Schema has 100% description coverage; the description further enriches with concrete examples for each type and delivery channel (e.g., parameters format for sec_8k, delivery constraints). This adds meaningful context beyond the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription, returns a new subscription ID, and lists supported event types and delivery channels. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by being the creation tool.

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

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

The description includes prerequisites (Pipeworx OAuth account, not anonymous/BYO), gives type-specific examples (e.g., sec_8k for SEC filings, polymarket_edge for cross-venue arbitrage), and mentions delivery channel constraints. However, it does not explicitly contrast with alternative tools for retrieving or managing subscriptions.

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 the tool safe (readOnly, idempotent, non-destructive). The description adds meaningful behavioral context by explaining that the tool returns category-bucketed example questions with exact tool and argument shapes drawn from a live catalog. It does not disclose potential response size or latency, but this is sufficient for an onboarding tool.

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

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

The description is somewhat long but efficiently packs trigger phrases, purpose, parameter details, and usage context. It is front-loaded with common user questions. While every sentence adds value, it could be slightly more concise without losing 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 that there is no output schema, the description effectively explains what the tool returns (category-bucketed example questions with tool shapes). The tool has low complexity (one optional parameter, 100% schema coverage), and the description covers all necessary aspects for an onboarding entry point.

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% (one optional parameter). The description adds significant value beyond the schema by listing example topic values (finance, pharma, etc.) and explaining that omitting the parameter yields a cross-category spread. This clarifies usage and matches user expectations.

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: returning category-bucketed example questions to help users understand what Pipeworx can do. It provides specific trigger phrases and distinguishes from sibling tools like ask_pipeworx by focusing on generating sample questions rather than directly answering queries.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and to learn how to call meta-tools. It also describes the optional topic parameter and that no arguments give a full spread. However, it does not provide explicit when-not-to-use guidance or list alternatives for other scenarios.

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

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

The description adds significant behavioral context beyond annotations, including ownership enforcement, deactivation (not deletion), and side effects (historical events via recent_alerts). Annotations only hint at non-destructive and idempotent behavior.

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

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

The description is extremely concise with two sentences, each adding essential information: the action and constraint, then the behavioral nuance. 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 one-parameter tool, the description covers the purpose, constraints, and side effects. While it omits the exact return value, the context is sufficient for an agent to use 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 schema already provides 100% coverage with a description for the 'id' parameter. The tool description does not add additional meaning to the parameter beyond what the schema states.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource, and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the effect (deactivation vs deletion) and referencing 'recent_alerts' for historical events.

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 indicates when to use the tool (to cancel a subscription) and enforces ownership, but does not explicitly state when not to use it or provide direct alternatives. However, the context is clear enough for typical use.

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

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

The description fully discloses behavioral traits beyond annotations. It details the return value (verdict, actual value with citation, reasoning), the two distinct processing paths, and the idempotent/read-only nature consistent with annotations. 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 dense but well-structured, starting with example queries, then explaining the two pathways, and ending with return value summary. While it is a single paragraph, it efficiently conveys necessary information without excessive verbosity.

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 (two processing paths, multiple verdict types, integration with SEC EDGAR), the description is remarkably complete. It explains the fallback behavior, return format, and why it replaces multiple calls. No output schema is present, but the description adequately covers return values.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the tolerance_pct default and suggesting use cases like hallucination detection. It also provides more context for the claim parameter, going beyond the schema.

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

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

The description clearly identifies the tool's purpose as verifying natural-language factual claims against authoritative sources. It provides specific example queries ('Is it true that…', 'fact check', etc.) and contrasts with sibling tools by noting it replaces 4-6 sequential calls, making the purpose distinct.

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 when to use the tool ('whenever the agent needs to check factual correctness') and explains the two processing paths (fast path for company financials, grounded pipeline for other claims). However, it does not explicitly enumerate situations where an alternative tool would be preferred, leaving some ambiguity.

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