Entur

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by detailing the default model, the need for a BYO API key for Anthropic, and the per-model return structure (score, confidence, signals, raw_response) plus a combined view. No contradictions with annotations.

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

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

The description is three sentences that front-load the core purpose, then add details in a logical order. Every sentence contributes value without redundancy.

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

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

Given the tool's 4 parameters, no output schema, and annotations covering safety, the description fully explains what the tool does, how to use it (default vs. paid models), and what the response contains. An agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100% for all 4 parameters. The description goes beyond the schema by explaining default behavior (free Workers AI model) and the purpose of the context parameter (disambiguating common names). This adds meaningful context for parameter usage.

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

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

The description uses specific verbs ('probe','score') and clearly identifies the resource (LLMs) and output (visibility score 0-100). It distinguishes itself from sibling tools by focusing on AI visibility measurement for businesses/brands/products/topics.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and how to use the optional _apiKey for Anthropic. It does not explicitly list when not to use, but the context is clear.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description adds behavioral context: routing across 5,521 tools, filling arguments, returning structured answers with stable citation URIs, and one fast call. No contradictions with annotations, and it goes beyond the structured fields to explain the tool's internal 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 lengthy but every section earns its place: scope, examples, alternatives, and technical behavior. It is front-loaded with a strong directive and remains structured despite 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?

The tool has no output schema, but the description explains the return format (structured answer with citation URIs). It covers purpose, usage guidelines, examples, and alternatives, making it a complete description for this 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% with six parameters all described as aliases for 'question'. The description adds no parameter-level details beyond the schema, so baseline 3 is appropriate; the schema already fully documents the required input.

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 routes factual questions to appropriate verified sources and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by noting when to step up, and provides a clear scope with examples.

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 says to prefer this over web search for factual questions, provides trigger phrases, and names alternatives for specific use cases (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). It also clarifies that breaking-news is handled within this tool, so no exclusion ambiguity.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that this is an experimental edge with candidate routing, that no candidate is currently active, and that it is a full working router with no fallback (contradicting a possible assumption that it might be a thin wrapper with degraded functionality). This is valuable context for an agent deciding whether to use it.

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 but each earns its place, conveying purpose, current status, usage guidance, and a key clarification. It is front-loaded with the core identity ('Beta version of ask_pipeworx') and avoids redundancy, though a slightly tighter wording could be possible.

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 gives a complete picture for an agent deciding whether to invoke this tool: what it is (beta router), how it relates to ask_pipeworx, current behavior (matches stable), and usage guidance. It references the same response shape as ask_pipeworx, and since there is no output schema, the description does not need to detail return format further. Minor gap: it does not explicitly define what 'universal router' does, but this is likely known from ask_pipeworx 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?

The description provides no parameter-specific information, but the input schema already documents all parameters with 100% coverage, including aliases. Therefore the schema carries the full burden, and the 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 is a beta version of ask_pipeworx, a universal router, and explicitly differentiates it by mentioning candidate routing improvements and the current exact match to ask_pipeworx. This gives a specific verb-resource (ask beta router) and distinguishes it from the stable sibling ask_pipeworx.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router, noting results are compared. It also clarifies the current inactive state so the agent knows it behaves identically to ask_pipeworx right now.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses refusal reasons, evidence quotes, confidence scoring, and the extra LLM call cost. It explains that the tool only uses data from the tool result and will explicitly refuse when it cannot answer, adding significant behavioral context without contradicting annotations.

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

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

Dense but front-loaded with the core purpose ('Hallucination-resistant answer mode'). Each sentence adds value: routing, extraction method, return format, refusal conditions, usage context, and cost tradeoff. No wasted words; the length is justified by the tool's complexity.

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

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

The description fully documents return values, refusal reasons, usage context, and cost implications, even though no output schema is provided. It covers all necessary behavioral aspects for an agent to decide when and how to invoke this tool, making it contextually complete.

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

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

Schema coverage is 100% — the question parameter and its aliases are fully described in the schema. The description does not add new parameter-specific semantics beyond reiterating that the input is a natural language question. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode' that uses the same routing as ask_pipeworx but extracts answers strictly from tool results. It distinguishes from the sibling ask_pipeworx by emphasizing evidence-based extraction and explicit refusal behavior, making the purpose highly specific.

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: for high-stakes reads where answers will be quoted, cited, or acted on, and where facts must not be invented. Also specifies when not to use: prefer ask_pipeworx for casual lookups, citing the extra LLM call cost. Names the alternative tool directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint = false. The description adds substantial behavioral context: resolver contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback mechanisms, safety (low-confidence short-circuit, closed market handling, wide-spread risk), and resolution-rule risk (cancellation_rule). This far exceeds basic annotation information.

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 (multiple paragraphs) and contains extensive detail. While comprehensive, it could be more concise. Some details like the full list of classifiers and fan-out examples could be summarized or linked. However, it is front-loaded with the purpose and main usage. Still, it is verbose for a tool description.

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, so the description must explain return structure. It does so comprehensively: market fields (best_bid, best_ask, etc.), analysis fields (model_probability, edge_pp, kelly_fraction_half, 24h-move warning), evidence keyed by source, resolver contract, parent_event extractor, news fields, safety statuses, and cancellation rule. All edge cases are covered.

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

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

Schema description coverage is 100%. The description adds meaning by explaining each parameter: 'market' accepts slug, URL, or question text; 'depth' has enum and default; 'include_raw' explains purpose and size consequences. It also provides examples. This adds significant value beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data in one call, with specific verb 'Research' and resource 'Polymarket bet'. It also distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on data collection and evidence rather than pricing or edge calculation.

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 for should I bet on X, what does the data say about Y, or is there edge in Z' and provides examples. However, it does not mention when not to use it or what alternatives (e.g., ask_pipeworx) might be better for simpler queries. Still, it gives clear usage 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting 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?

The description is somewhat lengthy but front-loaded with key phrases and examples. Every sentence adds value, though minor trimming could improve conciseness.

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

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

For a tool with two fully-covered parameters and comprehensive annotations, the description covers data sources, parallel call benefit, and output format (paired data + citation URIs). No missing critical aspects.

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 meaningful context: explains the difference between company and drug types, provides examples of valid values, and clarifies sorting behavior.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with clear examples like 'Compare X and Y' and distingushes from sequential single-pack lookups.

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

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

The description gives strong guidance to prefer this tool over sequential lookups when comparing entities, but does not explicitly state scenarios where this tool should not be used.

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

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

The description goes far beyond the annotations by disclosing account requirements, paid depth tier, parallel decomposition into facets, explicit gaps[] that 'never invented', resolvable pipeworx:// citations, second-hop iteration, contradiction scans, semantic excerpting, and expected latency. This rich context is absent from the annotations and is essential for an agent to anticipate the tool's 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 every sentence carries useful information. It is front-loaded with account requirements and key alternatives, though it could arguably open with the core function. The structure is logical: account, purpose, mechanics, output, usage guidance, depth semantics, performance. Slightly verbose in the depth explanation, but justified 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?

With no output schema and only two simple parameters, the description fully carries the burden of explaining return values, limitations, and edge cases. It covers the findings packet, gaps, contradictions, citation format, semantic excerpting, data coverage, and timeouts. For a tool of this complexity, the description is remarkably complete and self-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?

Even though schema coverage is 100%, the description adds substantial meaning to both parameters. It explains the depth values in detail (quick/standard/thorough with hop behavior, defaults, paid restriction) and clarifies that 'Broad/multi-part is fine' for the question parameter. The description also ties parameters to output behavior and performance expectations, going well beyond the schema text.

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

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

The description clearly states a specific action: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources... in ONE call'. It distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and by contrasting with ask_pipeworx for single lookups and breaking news. The verb, resource, and scope are all 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 provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and even handles account constraints ('If you are not signed in, use ask_pipeworx instead'). It names the alternative tool directly, making the decision boundary clear.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate safety. The description adds beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 front-loaded with purpose and usage, then details what is returned. While efficient, it is slightly long due to listing many domains and the full schema in the description area. Every sentence earns its place, but could be trimmed without losing meaning.

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

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

Given 6 parameters (1 required), no output schema, and no nested objects, the description fully covers purpose, usage, return content (names, descriptions, schemas, ready to call), and parameter aliases. No gaps are evident for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so description only needs to add context. It clarifies that 'query' accepts natural language and lists multiple aliases (task, q, description, search). This adds value beyond the schema's individual descriptions by grouping them.

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

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

The description starts with a clear verb+resource: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a discovery layer, not a domain-specific 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 states when to use: '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 and want to see the option set.' It provides clear context but does not explicitly say when not to use it, which would be helpful.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: returns specific fields (CIK, filings, fundamentals, patents, news, LEI), notes patent data soft-fails until May 2025, and mentions parallel execution. 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 relatively long but front-loaded with examples and key information. Each sentence adds value; no obvious wasted words. Could be slightly more concise, but structure is clear and logical.

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

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

Given the tool's complexity (multiple sources, parallel execution, soft-fail for patents), the description is complete. It enumerates all returned data fields, mentions the GDELT→GNews fallback, and explains the LEI source. No output schema exists, but the description sufficiently covers return values.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning beyond the schema: type is limited to 'company' for now, value can be ticker or zero-padded CIK, and explicitly warns that names are not supported. This compensates for the schema's otherwise terse descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the verb ('profile'), resource ('US public company'), and scope ('cross-source'), distinguishing it from siblings like resolve_entity by noting that names are not supported.

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

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

Provides explicit examples of when to use ('Tell me about X', 'research Acme', 'brief me on Tesla') and states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies when not to use: if only a name, use resolve_entity first.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the exact data returned (line, destination, times, delay, platform, realtime flag) and confirming real-time nature, which is not detailed in annotations.

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

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

The description is extremely concise: two sentences plus an example code snippet. Every sentence adds value without redundancy. It is front-loaded with the core purpose.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description fully covers what a user needs to know: scope, usage, returned fields, and an example. 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?

Input schema has 100% description coverage. The description further enhances semantics by including an example that demonstrates the stop and mode parameters, and explains mode enums (e.g., 'water = ferry/boat, rail = train'). Default limit of 10 is mentioned.

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 it is a real-time departures board for any public-transport stop in Norway, listing modes and providing an example. This clearly differentiates it from sibling tools like entur_journey (journey planning) and entur_stops_search (stop lookup).

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

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

The description includes a clear usage example and implies its use for retrieving departures for any Norwegian stop. While it does not explicitly state when not to use it compared to siblings, the specific focus on departures provides sufficient 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?

The description adds behavioral detail beyond annotations by explaining the return structure (itineraries with legs, times, duration, etc.) and mentioning it is a planner (read-only, idempotent confirmed by annotations). It does not contradict annotations.

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

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

The description is concise (two sentences plus an example) and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains return values. It covers scope, required parameters via example, and optional ones. With 5 parameters and 100% schema coverage, the description is complete for selecting and invoking the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description includes an example that illustrates usage but does not add significant meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: planning public-transport trips in Norway. It specifies the verb 'plan', the resource 'public-transport trip', and the geographic scope. It also distinguishes from sibling tools like entur_departures and entur_stops_search by focusing on door-to-door itineraries.

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

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

The description provides clear usage context with examples and mentions specific scenarios (train, airport, city routes). However, it does not explicitly exclude use cases or name alternatives, which would enhance guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it uses the 'Entur national stop-register geocoder' and lists return fields, but these do not significantly extend behavioral knowledge beyond the annotations.

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

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

The description is two sentences: one explaining the tool's purpose and output, and one giving a concrete example. There is no fluff, and each sentence is valuable.

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

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

Given the simple input schema (2 params, 100% coverage), comprehensive annotations, and no output schema, the description sufficiently explains what the tool does and what it returns. The inclusion of an example and the link to sibling tools makes it complete 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 description coverage is 100%; both 'query' and 'limit' are well-described in the schema. The description provides an example call but does not add new semantic meaning beyond what the schema provides.

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

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

The description clearly states the verb 'search' and the resource 'Norwegian public-transport stops...'. It specifies the return fields including the NSR id, which connects to sibling tools entur_departures and entur_journey, effectively distinguishing its purpose.

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

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

The description implies that this tool is a prerequisite for entur_departures and entur_journey by mentioning that the NSR id is usable in those tools. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use 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 already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns. The description adds context about clearing sensitive data, but not much else beyond what annotations provide. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two sentences, no redundancy. The first sentence immediately states action and resource, the second provides usage guidance. Every word earns its place.

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

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

For a simple, single-parameter tool with no output schema and strong annotations, the description covers purpose, usage, and behavioral context adequately. Nothing is missing.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description adds 'previously stored' but does not elaborate on format or constraints. Baseline 3 applies as schema handles 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 states the tool's purpose: deleting a previously stored memory by key. It uses specific verb ('delete') and resource ('memory by key'), and the pairing hint with 'remember' and 'recall' distinguishes it from sibling tools.

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

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

The description explicitly lists when to use (stale context, task done, clear sensitive data) and hints at pairing with siblings. It does not explicitly state when not to use, but the guidance is sufficient for a simple 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 readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds behavioral details: it fetches the page, extracts metadata, and outputs standard markdown. It does not contradict annotations and provides useful context beyond them.

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 effectively communicates purpose, behavior, and use cases. It is concise but could be slightly more structured (e.g., bullet points for use cases).

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

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

With 2 parameters, no output schema, and thorough annotations, the description adequately covers the tool's behavior and output (single text blob). It doesn't explain error handling or edge cases, but for a simple read-only tool, this is 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% with both parameters described. The description repeats some info (default 25, max 50 for max_links) but adds no additional semantics 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 the tool's purpose: generating a production-ready llms.txt file for a given URL, with specific verbs ('generate', 'fetches', 'extracts', 'emits') and resource ('llms.txt file'). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' or 'deep_research' by focusing on this specific output format.

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 concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly state when not to use the tool or mention alternatives, though none are obvious 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds behavioral context by listing returned fields and the optional include_inactive parameter, without contradicting annotations.

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

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

Two sentences, front-loaded with the core action and returns, 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 tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage guidance adequately.

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

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

Schema coverage is 100% and the description does not add extra meaning beyond what the schema already provides for the single parameter.

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

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

Clearly states the verb 'list' and the resource 'subscriptions', specifies scope as 'caller's active' and enumerates return fields, distinguishing from sibling tools 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?

Provides explicit guidance on when to use ('review what you're monitoring before adding more or to find an id to cancel'), but does not mention 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?

The description goes well beyond the annotations (which only say readOnlyHint=false, no destructive hint). It explains the full behavioral contract: filing returns a `claim_token`, which can later be passed back to read status and resolution details; it's rate-limited to 5 per identifier per day; it's free and doesn't count against tool-call quota; and the team reads digests daily. This gives the agent a clear model of side effects and constraints without contradicting annotations.

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

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

The description is relatively long (around 170 words), but every sentence contributes necessary operational detail: purpose, use cases, exclusions, token flow, rate limits, and team behavior. It is front-loaded with the core purpose and structured logically. A minor deduction for length because a few clauses could be tightened (e.g., 'Not sure?' clarification), but it remains appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description fully explains what to expect (claim_token, later status reply) and covers all relevant operational aspects: when to use, when not to use, how to reference tools, constraints, and follow-up mechanics. This is complete for a feedback submission tool, with no obvious gaps.

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 extra meaning by explaining the `claim_token` workflow explicitly (`pipeworx_feedback({claim_token:"pwfb_…"})` with no other arguments) and by providing practical guidance on message length ('1-2 sentences typical, 2000 chars max'). This adds value beyond the schema's field descriptions, making the parameter semantics clearer.

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, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team) and the verb (tell/feedback), and clearly distinguishes from sibling tools like ask_pipeworx, which are for asking questions rather than sending feedback. It also distinguishes from external server feedback by explicitly limiting scope to Pipeworx connection tools.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a concrete exclusion: tools from other MCP servers should be filed with that server, not here. This clearly directs the agent to the correct alternative behavior.

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, destructiveHint. Description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching duration (5min-1h). 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?

Three concise paragraphs: purpose, use cases (bulleted), source/caching info. Front-loaded with key action. Every sentence adds value. 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?

Returns described as top tools, top packs, total call volume but no detail on format, limits, or pagination. Since no output schema, description should clarify structure. Simple tool, so score is adequate but not fully complete.

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

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

Single parameter 'window' with 100% schema coverage. Description adds practical guidance on how window choice affects results (hot vs. steady-state), going beyond schema enum. Could further clarify default behavior.

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 'Returns the top tools, top packs, and total call volume over a recent window' with specific verb and resource. Distinguishes from sibling tools like discover_tools and search_within by focusing on aggregated trending data rather than search or discovery.

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

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

Explicitly lists three use cases and explains window selection (shorter for hot, longer for steady-state). Does not explicitly state when not to use, but context is clear. Could mention alternatives like discover_tools for non-trending discovery.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and the description aligns with these. It adds rich behavioral context: semantic anchor (Jaccard similarity), partition filter, fill check, and description of response structure. No contradictions with annotations.

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

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

The description is well-structured starting with a clear one-liner, followed by detailed mode explanations and algorithmic details. While every sentence adds value, the length could be slightly reduced without losing clarity. It is not wasteful but on the longer side.

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 (two modes, multiple checks, no output schema), the description thoroughly covers behavior, edge cases (placeholder slugs, low similarity), and response format. It also references a sibling tool for further sizing, making it self-contained enough for the agent to use correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds meaningful extra detail: for event, 'Full Polymarket URLs also accepted', and for topic, explains that it searches related events across the platform. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three distinct modes (trending scan, event mode, topic mode) and provides examples, making it easy to understand what the tool does and how it differs from other 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?

Explicit guidance is given on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns when not to trade based on the fill check, and points to the alternative tool polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details like 1-hour KV-level caching and response segmentation, surpassing annotation coverage without contradiction.

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

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

The description is approximately 500 words, highly detailed but verbose. While well-structured, it could be shortened without losing essential information.

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

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

Given 9 parameters, no output schema, and annotations present, the description fully covers response structure, segments, diagnostics, caching, and filter knobs, leaving no major gaps.

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?

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds overall context but does not significantly enhance individual parameter semantics beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for edges where Pipeworx data disagrees with market price, using a specific verb+resource. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-data disagreement.

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

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

The description indicates it is for 'what should I bet on today' and explains use of tradeable-edge knobs, but does not explicitly contrast with sibling tools 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 indicate read-only, idempotent, non-destructive behavior. The description adds significant context: snapshot reading, trend computation, expiration tracking, snapshot gaps, TTL limits, and decay calculation details. 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 dense but front-loaded with purpose. Each sentence adds value, though some sections (like the response structure) could be more concise. Overall efficient for the complexity.

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

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

Given no output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and covers edge cases (snapshot gaps, TTL limits, decay computation). Fully addresses 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 covers both parameters fully. Description adds default values (14 for days), clamps (2-30), and clarifies the 'window' parameter with examples. This goes beyond the schema's basic type 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 provides 'edge persistence and decay telemetry' and answers a specific question. It distinguishes itself from siblings like polymarket_edges by focusing on historical time-series rather than 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 implies when to use this tool (for edge persistence analysis) versus alternatives (like polymarket_edges for current edges). However, it does not explicitly state when not to use it or name 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are all consistent with the description. The description adds behavioral context: it walks the ladder, returns verdict (clean/degraded/cannot_fill), warns about thin legs and forced directional risk. 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 relatively long but well-structured with clear sections for single-market and basket modes. Every sentence adds value, though minor redundancy exists (e.g., explaining both modes in detail). It is front-loaded with the core purpose and usage guidelines.

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 modes, many parameters, no output schema), the description is comprehensive. It covers inputs, process, outputs (listing return fields), risks (thin books, partial fills), and usage context. No gaps remain for effective 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 description coverage is 100%, but the description adds meaning beyond the schema. For example, it explains how size_usd is interpreted differently in single-market vs basket mode (max spend vs target proceeds vs settlement notional). It also clarifies default side behavior in basket mode (auto from partition sum). This adds significant semantic value.

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

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

The description clearly states the tool is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It specifies two modes (single-market and basket), explains what each mode does, and lists outputs like top_of_book, vwap_fill_price, slippage_pp, verdict, etc. This distinguishes it well from siblings like polymarket_arbitrage and polymarket_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 explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position. This provides clear when-to-use and why-not 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?

The description goes beyond annotations (readOnlyHint, idempotentHint) by detailing behavioral traits such as bet shape compatibility checks, safety fields (compatibility_warning, temporal_alignment, skipped counters), and the fact that real spreads are rarer than the shortcut list suggests. 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 relatively long (multiple paragraphs) but is front-loaded with the main purpose. It contains valuable detail but could be more concise. It is structured with clear sections (modes, response, safety fields).

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

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

Given the complexity of the tool (3 parameters, no output schema), the description provides thorough context for understanding return values, including compatibility_warning, temporal_alignment, and skipped counters. It adequately covers what the tool returns and how to interpret results.

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

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

The input schema has 100% description coverage for all 3 parameters. The description adds some value by explaining the topic list and the override behavior of explicit tickers, but the schema already covers the basics. 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 that the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('computes', 'returns') and distinguishes itself from sibling tools like polymarket_arbitrage and other polymarket tools by focusing on cross-venue comparison.

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

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

The description explicitly describes two modes (topic shortcuts and explicit tickers) and provides guidance on interpreting results (e.g., compatibility_warning, temporal_alignment). While it doesn't explicitly compare to alternatives, it implicitly tells when to use this tool (for cross-venue spreads) and when to be cautious.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already cover basic behavior. Description adds valuable context: scoping to identifier and the omitting-key behavior for listing all keys, which are not in 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 sentences, no wasted words. Purpose is front-loaded. Examples embedded naturally. Efficient and clear.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description fully covers purpose, usage, and behavioral nuances. No gaps apparent.

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

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

Schema coverage is 100% with a clear description of the optional 'key' parameter. The tool description repeats the behavior of omitting the key to list all keys, adding little new to what schema already provides, 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?

Clear verb ('Retrieve', 'list') and resource ('value previously saved via remember', 'all saved keys'). Distinguishes from siblings (remember, forget) by explicitly stating it pairs 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 states when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget, but does not provide explicit when-not-to-use or alternatives beyond the sibling 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 indicate safe, read-only, idempotent. Description adds behavior: mark_read=true flags events read so next call shows newer ones. 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?

Single paragraph, front-loaded with main action. Efficient but could be slightly more structured. No wasted sentences.

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 explains return fields (source, citation_uri, payload). Covers all parameters, provides usage examples, and mentions polling suitability. Complete for a read-only retrieval tool.

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

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

Schema coverage 100% with descriptions. Description adds examples ('sec_8k'), explains effect of mark_read, and clarifies since expects ISO timestamp. Adds value beyond schema.

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

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

Clear verb+resource: 'Pull fired events from your subscription feed.' Specifies what it returns (alerts with source, citation_uri, payload). Distinct from sibling tools like list_subscriptions.

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

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

Provides context: 'Polls work fine' suggests suitable for repeated calls, and mentions alternative access via URL. Does not explicitly state when not to use, but gives sufficient 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?

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.), detailing the data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), rate limits, soft-failures, and return format (changes grouped by source, total_changes count, citation URIs). 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 a single dense paragraph but is front-loaded with clear usage examples and covers all key aspects without unnecessary words. It could benefit from slight structuring, but it remains efficient and informative.

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 (multiple data sources, fallback logic, and no output schema), the description adequately explains the return structure (changes array, total_changes, citation URIs) and source behaviors. It covers the USPTO limitation and GNews fallback, making it fairly 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?

All three parameters have schema descriptions (100% coverage). The description enhances them with practical examples (e.g., '7d', '30d', '3m', '1y' for `since`) and constrains the `type` parameter to 'company'. This adds value beyond the schema.

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

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

The description clearly states the tool retrieves a change feed for a company over a specified window, using specific verbs like 'What's new with X' and 'latest on Y'. It distinguishes itself from the sibling tool 'entity_profile' by directing to use that for static profiles.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' ('Use entity_profile instead when you want the static profile'). It also includes example queries. It does not explicitly state when not to use it, but the alternative is clearly named.

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 idempotentHint=true and destructiveHint=false. The description adds critical behavioral details: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. It also explains how it pairs with recall/forget. 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 tightly written in three sentences with no extraneous text. It front-loads the core purpose and then efficiently adds context (scoping, retention, pairing) without redundancy.

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

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

For a simple tool with 2 required parameters and no output schema, the description covers all necessary aspects: purpose, usage scenarios, behavioral traits, and how it integrates with sibling tools. No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces this with usage examples ('subject_property', 'target_ticker') and context, adding meaning beyond the schema alone. While the schema already covers format, the description's examples enhance semantic understanding.

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

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

The description states a specific verb-resource pair ('Save data...to reuse later') and clearly defines the tool's function as storing key-value pairs. It distinguishes from siblings by naming recall and forget as complements, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('when you discover something worth carrying forward') with concrete examples. It suggests pairing with recall and forget but does not explicitly state when not to use the tool. This is a minor gap, but the context is clear enough.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral context: auto-disambiguation, cascading through endpoints internally, and specific return fields including citation URIs. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat lengthy but well-structured with example queries, supported types, and return details. Each sentence adds value, though the opening example list could be trimmed without losing meaning.

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

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

Given there is no output schema, the description thoroughly explains what the tool returns for each entity type, including specific fields and citation URIs. It also notes internal cascading behavior. This is sufficient for an agent to understand the tool's behavior and output.

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 covers 100% of the parameters, so the baseline is 3. The description adds practical examples and explains accepted input formats (ticker, CIK, name for company; brand/generic for drug), which enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool resolves a spoken name to a canonical identifier needed by other tools, with explicit verbs and resources (e.g., ticker, CIK, RxCUI). It distinguishes itself from sibling tools like entity_profile by focusing on ID resolution rather than profiling.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, clarifying its efficiency. While it doesn't explicitly name alternatives, the context strongly implies when it should be chosen over other 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?

Description discloses internal probing via ai_visibility_check, ranking, and output fields (score, confidence, signal density). Annotations already show readOnly, idempotent, safe; description adds valuable behavioral details without contradiction.

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

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

Two sentences plus a usage example. Front-loaded with primary action. No redundant information; 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?

Despite no output schema, description specifies return format (ranked list with score, confidence, signal density). Explains internal mechanism and when to use. Fully sufficient for an AI agent to select and invoke correctly.

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

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

Schema coverage 100%. Description adds meaning beyond schema: first entity is 'subject' for narrative, rest competitors; mentions internal tool call; explains all param roles (models, apiKey, context) in context of comparison.

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 'Compare AI visibility across multiple entities side-by-side' with specific verb+resource. Differentiates from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (general) by focusing on AI presence ranking.

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?

Includes explicit use case: 'competitive AI-marketing audits' and example question. Implicitly guides against single-entity checks (use ai_visibility_check). No explicit when-not, but adequate for 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 show readOnly, openWorld, idempotent, non-destructive. The description adds crucial behavioral details: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, sources_failed lists timeouts. This provides depth beyond annotations.

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

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

The description is well-structured and front-loaded. It provides essential information without verbosity. Every sentence adds value, though it is somewhat lengthy for a concise tool description.

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

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

Given the tool's complexity and lack of output schema, the description sufficiently explains the return format (summary block, per-advisory detail, links, alternatives). It covers failure modes and ecosystem scope. Minor gaps: does not specify exact fields in summary beyond listing them.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds value by clarifying that scoped packages are accepted and that version defaults to latest. This goes 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 specifies the tool as a composite check for npm packages, covering license, advisories, bundle size, etc. It uses specific verbs and resource (scan dependency) and distinguishes from siblings by focusing on npm ecosystem.

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: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes ecosystem scope (NPM only) and alternatives (deps.dev:version for other ecosystems).

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds details: returns top-N passages with offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char windows, and clarifies truncation behavior. 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 with rich information. Front-loaded with core purpose, then technical details. Every sentence is valuable.

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 (semantic search, windowing, offsets, pairing), the description is comprehensive. It explains the return format and caveats without needing an output schema.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains embedding model, window size, and that offsets are returned. Provides natural-language query examples.

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 performing semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning pairing with 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?

Explicitly states when to use (when record is too large) and provides an alternative pairing. Also includes constraints (200K char limit, truncation flag).

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 readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral details: returns new subscription id, delivery channel constraints (phone verification, 10/day SMS cap, webhook secret returned once, auto-disable on failures), and type-specific parameters. No contradictions with annotations.

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

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

The description is well-structured with clear sections for types and delivery channels. However, it is somewhat lengthy with extensive examples; while valuable, 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 the tool's complexity (multiple types, nested params, delivery options, constraints), the description provides thorough context including return value, constraints, and examples. It lacks information on error handling or permissions beyond OAuth, but the provided details are sufficient for most use cases.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema. It explains each subscription type's params format with concrete examples (e.g., 'items:["5.02"] = officer change'), and details delivery channel properties (e.g., webhook HMAC signing). This greatly aids correct parameter usage.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (subscribe), the resource (alert subscriptions), and distinguishes from siblings like 'list_subscriptions', 'unsubscribe', and 'recent_alerts'.

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 the tool and outlines prerequisites (Pipeworx OAuth account, no anonymous/BYO). It lists supported subscription types with examples and mentions delivery channels. However, it does not explicitly state when not to use it or compare with similar 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?

The description adds significant behavioral context beyond annotations: it's an onboarding tool, returns category-bucketed examples with exact tool+argument shapes, and explains no-argument vs topic-filtered calls. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and reinforced.

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

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

The description is well-organized and front-loaded with key information. However, it is slightly verbose with many examples and details; a more concise version could still be effective. Still, every sentence serves a purpose.

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

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

Given the absence of an output schema and the simplicity of parameters, the description thoroughly covers what the tool does, when to use it, and what results to expect. It is complete for an onboarding tool.

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

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

Schema description coverage is 100% for the single optional parameter. The description further clarifies the topic parameter with concrete examples ('finance', 'pharma', etc.) and explains the behavior when omitted, adding meaningful guidance beyond the schema.

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

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

The description clearly identifies the tool as an onboarding entry point for discovering what questions to ask Pipeworx. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by being the first tool to call.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides scenarios for when to use it. It also explains how to optionally focus with a topic parameter.

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 context beyond annotations: 'deactivated (not deleted),' ensuring agent understands persistence of historical events. Ownership enforcement is a key behavioral trait. Annotations (destructiveHint: false) align with description, no contradiction.

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

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

Three sentences, all essential: action, ownership rule, and deactivation behavior. No wasted words, efficiently conveys all needed info.

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 param and no output schema, description covers purpose, ownership, and deactivation semantics. No missing critical information.

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?

Single parameter 'id' already fully described in schema (100% coverage). Description adds value by noting 'returned by subscribe,' linking to related tool. Baseline 3, incremental value gives 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?

Clearly states 'Cancel a subscription by id.' Identifies specific verb (cancel) and resource (subscription by id). Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' guiding when to use. Also clarifies that deactivation differs from deletion, providing context on effects. No alternative tools mentioned but sufficient for this simple 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: it returns a verdict with evidence and citations, explains internal routing (SEC fast path vs grounded pipeline), and confirms no data mutation. 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 moderately long but well-structured: trigger phrases first, then processing logic, then return format. Each sentence adds information without redundancy. Could be slightly more concise 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?

Despite no output schema, the description fully covers return values (verdict type, actual value with citation, reasoning) and processing behavior. For a tool with only 2 parameters, the description is complete and leaves no gaps for an agent to infer.

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 meaning: explains tolerance_pct overrides implied tolerance and gives usage examples, and clarifies claim is a natural-language factual statement. Adds value beyond schema.

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

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

The description precisely states the tool's purpose: natural-language claim verification against authoritative sources. It provides trigger phrases and distinguishes between company-financial and other claims, clearly differentiating it from sibling tools like ask_pipeworx and deep_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the two processing paths (structured vs grounded) with fallthrough behavior. While it doesn't enumerate when not to use, the context is clear enough for agent decision-making.

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