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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description goes beyond that to disclose routing behavior across thousands of internal tools, argument filling, structured output with citation URIs, and the claim of 'one fast call' on every tier. No contradiction exists.

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

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

The description is long (~260 words) but effectively front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and key facts. Nearly every sentence earns its place, though there is some repetition: 'START HERE', 'default entry point', and 'works on every tier' overlap. Still, the structure with trigger phrases, examples, and step-up guidance is well organized.

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

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

For a complex read-only tool with no output schema, the description covers input type, routing behavior, expected output type (structured answer with citations), and when to use sibling tools. It does not describe exact output formatting or pagination, but the guidance is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with the 'question' property and its aliases (q, text, input, query, prompt) fully documented. The description adds usage examples but no additional parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

The description states a specific verb and resource: it routes questions to the right one of 5,706 tools across 1,493 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, and positions itself as the default entry point for factual questions.

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 is explicit about when to use it: 'PREFER OVER WEB SEARCH' and lists trigger phrases like 'what is', 'look up', 'find', 'get the latest', plus concrete examples. It also gives clear exclusions: use ask_pipeworx_grounded for hallucination-resistant single answers, and deep_research for broad/multi-part questions. No inference is needed.

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 non-destructive behavior. The description adds meaningful context beyond these: live candidate routing improvements may be active, currently none are active (so it matches ask_pipeworx exactly), and it 'falls back to nothing' meaning it is a full working router rather than a degraded wrapper.

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, each contributing distinct information: beta status, equivalence to ask_pipeworx, usage guidance, and fallback clarity. There is slight redundancy in repeating 'identical' and 'same' but the overall structure is efficient and front-loaded with the key descriptor.

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?

As a router with no output schema, the description points to ask_pipeworx's response shape and explains the experimental edge, which gives an agent sufficient context to invoke it correctly. It does not spell out the response shape but correctly defers to the stable sibling.

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 provides 100% coverage, documenting the required 'question' parameter and all five aliases. The description only mentions 'same arguments' without adding parameter-specific semantics, so the schema carries the full burden and the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, explicitly calling it a 'universal router' with the same 5,706 tools. It distinguishes itself from the sibling tool by emphasizing the experimental routing improvements, so an agent can tell it apart from ask_pipeworx and ask_pipeworx_grounded.

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 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear usage trigger and naming the stable alternative. It does not explicitly list when-not-to-use scenarios, but the context implies stability-seeking agents should prefer 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?

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: exact return shape, explicit refusal reasons, evidence/confidence/source fields, and the extra LLM call cost. 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 every sentence earns its place: definition, routing mechanism, return shape, refusal behavior, usage guidance, and cost trade-off. The main purpose is front-loaded and no filler is present.

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

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

The description covers the return format on success and failure, enumerates refusal reasons, explains the routing and extraction behavior, and gives cost and usage context. With no output schema provided, this fully compensates for what an agent needs 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?

Schema description coverage is 100% and all parameters are aliases of question, so the schema already fully documents the parameter semantics. The description adds no new parameter-level detail, which is acceptable at this coverage level, yielding the baseline score.

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

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

The description clearly defines a hallucination-resistant answer mode that extracts answers only from tool results, with explicit reference to the sibling ask_pipeworx and its causal lookups. It states the mechanism and scope precisely, making it easy for an agent to distinguish this tool from the ungrounded variant.

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: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples. It also gives a clear exclusion: prefer ask_pipeworx for casual lookups because this mode costs one extra LLM call.

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?

Even though annotations already mark readOnly/openWorld/idempotent, the description adds substantial behavioral context: account tier requirements, parallel decomposition across 5,706 tools, return packet fields, gaps[] honesty behavior, semantic excerpting, latency expectations, and contradictions[] on deeper depths. No statement conflicts with the annotations.

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

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

The description is long but densely informative; almost every sentence carries a distinct fact (auth, source scope, output packet, alternatives, depth behavior, citations, latency). It is not perfectly front-loaded because the first sentence is an account-requirement gate rather than the core purpose, but the purpose follows immediately and no filler is present.

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

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

For a complex tool with no output schema, the description covers what an agent needs: when to use it, auth prerequisites, what results look like (evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), depth semantics, latency, and how citations are guaranteed fetchable. There is no significant missing context for selecting or invoking it.

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

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

Schema coverage is 100%, so the schema already documents 'question' and 'depth'. The description adds value by explaining that broad/multi-part questions are acceptable ('decomposition is the point') and elaborating what each depth mode does behaviorally (hop, gap recovery, contradictions pass, paid thorough). It mostly reinforces the schema rather than introducing entirely new parameter meaning, so slightly 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources... in ONE call.' It also explicitly differentiates from siblings by saying 'this is NOT open-web search' and by contrasting with ask_pipeworx, so an agent can identify when this tool applies.

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

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

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' This fully routes the agent among siblings.

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?

Beyond annotations (which only note readOnly/openWorld/idempotent/destructive hints), the description discloses the claim_token mechanism for later retrieval, rate limits (5 per identifier per day), quota exemption, and that the team reads digests daily. It also warns against pasting end-user prompts. 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 a single dense paragraph that front-loads the core action, then layers usage guidance, constraints, and follow-up behavior. Each sentence serves a purpose—no fluff or repetition.

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

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

Without an output schema, the description explains the return behavior (claim_token) and how to use it, plus rate limits and roadmap impact. It covers prerequisites (account vs. no account) and scope restrictions, making the tool understandable end-to-end.

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 fully documents all four parameters (100% coverage), so the description adds little beyond schema descriptions. It reiterates claim_token usage and message content guidance, but the schema already captures this. 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 opens with a clear directive ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates specific categories (bug, feature, data_gap, praise). It explicitly scopes the tool to Pipeworx-served tools, distinguishing it from sibling ask/discover 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 it (wrong/stale data, missing tool, praise) and when NOT to use it (tools from other MCP servers) with a redirect instruction ('file it with that server instead'). Also classifies uncertainty with 'Not sure? Pipeworx tool names are the ones this connection lists.'

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?

The annotations already declare readOnly, openWorld, and idempotent behavior, but the description adds substantial operational transparency: TWO MODES, compatibility_warning/codes semantics, the rule that unknown metric_type or match_subtype legs are never paired, skipped_cross_type/subtype counters, temporal_alignment, and the warning that most pre-mapped topics currently return warnings. No behavioral trait is hidden or contradicted.

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 and well structured, with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loaded purpose before caveats. Given the tool's complexity and lack of an output schema, nearly every sentence earns its place. It could still be tightened without losing value, which keeps it at 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?

With no output schema, the description must carry the full burden of explaining return values and edge cases, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, low_confidence_pairs, temporal_alignment, and skipped counters. It also covers non-obvious behavior such as never pairing unknown classification. An agent has enough information to call this tool and interpret its results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents the topic choices and the two override parameters. The description adds meaningful semantic value by explaining that an explicit ticker or slug overrides the topic-mapped side and by framing the parameters as two mutually distinct pairing modes. This enrichment justifies a 4, though the schema already carries much of the burden.

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

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

The description clearly identifies a specific resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, and it specifies that the tool compares equivalent bet shapes. It goes beyond the name by explaining the 2-25pp participant-pool divergence and the two modes. However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage or polymarket_edges, so it stops short of a 5.

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

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

The description gives explicit mode-level guidance: topic mode for pre-mapped shortcuts, and explicit kalshi_event_ticker plus polymarket_event_slug for custom pairings, including that explicit values override the mapped side. It also cautions that pre-mapped topics are not necessarily tradeable and often return compatibility warnings, which helps an agent set expectations. It does not name sibling tools as alternatives, so cross-tool routing remains implicit.

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 declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: identifiers are labelled with source, unresolved identifiers are explicitly returned rather than omitted, and enrichment degrades gracefully when external services (GLEIF/OpenFIGI) are unavailable. This goes well beyond the annotations and helps the agent predict tool 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 long but well-structured, starting with relatable example queries, then the core purpose, followed by supported types and fallback behavior. Every sentence adds value, though the opening query list is somewhat extensive and could be condensed. Overall, it is dense but not bloated.

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

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

The description is remarkably complete for a tool with no output schema. It explains what identifiers are returned, how they are sourced, how unresolved identifiers are handled, the graceful degradation path, and even notes that internal cascading reduces manual lookups. This gives the agent a full mental model of the tool's behavior and outputs.

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 type and value, but the description significantly enriches parameter meaning. It provides concrete examples (AAPL, CIK 0000320193, 'ozempic'), explains the ISIN-to-LEI mapping, and details what each entity type returns. This goes far beyond the basic schema descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with concrete examples like tickers, CIKs, and LEIs. It distinguishes itself from siblings by emphasizing that identifiers are 'required as input' by other tools, making it a dedicated lookup/resolution tool rather than an analysis or profile 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 explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also notes that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly name alternative tools or state when-not-to-use beyond the implied condition, so it lacks full 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 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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description discloses critical behavioral nuances: the meaning of could_not_verify (does not happen, must not be treated as evidence) and unsupported (no source found). This is valuable context that prevents misinterpretation of results and goes well beyond the annotation set.

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

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

The description is longer than average but every sentence serves a purpose: usage triggers, routing, return values, and error semantics. It is densely packed and front-loaded with examples, though a bit lengthy. It earns a 4 for structure and relevance, not a 5 for brevity.

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

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

With no output schema, the description fully explains return components (verdict list, actual value with citation, reasoning) and both error states (could_not_verify and unsupported). It also notes the tool consolidates 4–6 sequential calls, giving a complete picture for an agent. This is fully adequate 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?

The schema already provides 100% parameter coverage, with detailed descriptions for both claim (with examples) and tolerance_pct (including range, override semantics, and default). The tool description adds no new parameter-specific information, so the baseline of 3 is appropriate.

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

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

The description opens with concrete natural-language triggers ("Is it true that…", "fact check") and then states the tool's function explicitly: "natural-language claim verification against authoritative sources." It clearly identifies the specific verb (verify) and resource (claims), and distinguishes itself from general Q&A siblings by focusing on factual correctness checks.

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

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

The description gives explicit usage guidance: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains routing behavior for company-financial vs. other claims. However, it does not name specific alternative tools or provide explicit when-not-to-use scenarios, so it falls short of a 5.

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