Norges Bank

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context: the default model is free, Anthropic probing requires a BYO key with direct payment, and the return shape is described. This goes beyond 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 three sentences, front-loaded with the core action, followed by key details and use cases. Every sentence earns its place with no redundancy or filler.

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

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

Despite lacking an output schema, the description provides enough detail on return values ('per-model {score, confidence, signals, raw_response} + a combined view') and usage context. Minor gaps (e.g., what 'signals' actually contain) are acceptable given the tool's moderate 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining parameter behaviors beyond the schema: the default model (Workers AI Llama-3.3-70b), the free nature, and the cost implication of providing `_apiKey`. This enriches the understanding of the `models` and `_apiKey` parameters.

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

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

The description clearly states the tool's purpose with a specific verb ('Probe'), resource ('LLMs'), and subject ('business / brand / product / topic'). It also specifies the output (visibility score 0-100 per model). However, it does not explicitly distinguish itself from sibling tools like scan_competitor_ai_presence, so it stops short of a 5.

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

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

The description provides clear context with concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the default model versus providing an `_apiKey`. It does not mention when not to use the tool or alternatives, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavior context: it routes to many tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs. It also mentions 'works on every tier, one fast call,' which is beyond structured metadata.

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

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

The description is longer than ideal but every section earns its place: leading directive, domain list, trigger phrases, examples, escalation paths. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and is well-organized, though slightly repetitive about when to use it.

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

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

For a question-routing tool, the description covers the key contextual aspects: what it does, when to use it, what it returns (structured answer with citation URIs), and how it relates to siblings. No output schema exists, but the description gives enough information about the expected return style. It is comprehensive for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and clearly documents the main 'question' parameter with aliases. The description provides example queries (e.g., 'current US unemployment rate') that illustrate usage, but does not add deep semantic meaning beyond the schema's natural-language description. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It also lists specific data domains (SEC filings, FDA data, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded 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?

Explicit 'when to use' guidance is provided: 'Use whenever the user asks...' with trigger phrases and examples. It also names alternatives ('Step up only when needed') for ask_pipeworx_grounded (need verbatim evidence) and deep_research (broad/multi-part questions), plus clarifies that ask_pipeworx already handles live news.

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

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

The description goes well beyond the readOnlyHint, openWorldHint, and idempotentHint annotations by explaining that routing improvements may be enabled live when under test, that no candidate is currently active (matching ask_pipeworx exactly), and that it is a full working router with no fallback. This gives the agent a complete picture of the tool's current behavior and experimental risks.

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

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

The description is four sentences, each conveying essential information: identity, scope, current status, usage instruction, comparison behavior, and clarification that it is not a fallback. 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 one-parameter tool with comprehensive annotations and no output schema, the description fully covers the tool's purpose, usage timing, current beta status, and relationship to the stable router. It tells the agent everything needed to use and interpret results.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for 'question', so the schema itself is clear. The description does not add parameter-specific information, but it doesn't need to given the schema's completeness. Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental nature and live candidate testing.

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.' It also clarifies the alternative (stable ask_pipeworx) and notes that results are compared against the stable router, providing clear context for choosing this tool.

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

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

The description goes far beyond the readOnlyHint/openWorldHint annotations by disclosing behavioral traits: it costs an extra LLM call, returns a structured object with refusal reasons, and only extracts answers from the tool result (never invents). It also describes the possible refusal reasons, adding critical context for agent decision-making.

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 comprehensive but somewhat lengthy. It is front-loaded with the core purpose, then explains process, return format, use cases, and cost trade-off. Every sentence adds value, though it could be tightened. Not overly verbose for the complexity involved.

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 (large tool routing, extraction, refusal logic) and no output schema, the description fully covers return values on success (answer, evidence, confidence, source, fetched_at, refusal_reason) and on refusal (refusal_reason enum). It also explains when to use which sibling, making the description complete for agent invocation.

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

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

Schema description coverage is 100% – all parameters (question and aliases) are documented in the schema. The description does not add parameter-specific detail beyond what the schema already states, so the 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 a specific purpose: a hallucination-resistant answer mode for high-stakes reads. It details the process (same routing as ask_pipeworx, fetches data, extracts answer only from tool result) and distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also gives an alternative: 'prefer ask_pipeworx for casual lookups' – a clear when-not-to-use and alternative recommendation.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description goes far beyond this by detailing fan-out behavior, response shapes, resolver contract with market_match_confidence, parent_event extraction, the low_confidence_match short-circuit, blocking behavior for closed markets, wide-spread handling, and cancellation-rule risks. This adds substantial context that annotations cannot capture, with 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?

Although long, the description is structured with clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and is entirely information-dense. Each paragraph serves a purpose for agent decision-making. Given the tool's complexity, the length is appropriate and the key points are front-loaded with purpose and usage at the top.

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

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

With no output schema, the description fully explains return values: result.market, result.analysis, result.evidence, parent_event, news fields, and statuses. It also covers safety, blocking behaviors, and resolution-rule risk. This is comprehensive for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it repeats the market slug/URL/question text variants and does not deepen depth or include_raw semantics. The schema already documents all three parameters adequately.

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 begins with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It outlines the process (resolve, classify, fan out, return evidence packet + comparison) and clearly differentiates from sibling tools by focusing on whole-bet research rather than specific market data or edge calculations. The 'Use for' phrase provides concrete use cases.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes classifier types and fan-out examples, giving context for appropriate calls. However, it does not explicitly mention when NOT to use it or name alternative sibling tools for exclusions, so it stops short of a 5.

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

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

Despite strong annotations (readOnly, idempotent, openWorld), the description adds rich behavioral context: specific data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This goes far 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 front-loaded with the core purpose and examples, but it's slightly long. Some redundancy exists (mentions side-by-side comparison and also 'replaces 8–15 sequential lookups'), but every sentence contributes useful information. Not as tight as the best examples.

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

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

For a tool with no output schema, the description thoroughly covers return format (paired data + citation URIs), data sources, sorting behavior, and entity-type specifics. It answers likely agent questions about what data is returned and how results are ordered, making it highly 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?

Even though schema coverage is 100%, the description greatly enriches parameter meaning: it details exactly what type='company' vs 'drug' retrieves (e.g., revenue, net income, adverse event counts), and gives concrete examples for the values array. This adds substantial 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 performs side-by-side comparisons of 2–5 companies or drugs in a single call, with examples like 'X vs Y' and 'which is bigger'. It distinguishes itself from sequential lookups, making its purpose specific and 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?

Explicitly instructs to 'ALWAYS PREFER' over sequential single-pack lookups when comparing entities, and notes it replaces 8–15 sequential lookups. This gives clear when-to-use guidance, though it doesn't name a specific sibling tool as an alternative.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing key behaviors: returns 'gaps[] for facets the data couldn't answer (never invented)', includes 'contradictions[]' for standard/thorough, provides 'a stable pipeworx:// citation per finding', and explains semantic excerpting. It also manages expectations with timing ('Expect 15-60s... up to ~90s') and account requirements. No contradiction with annotations is present.

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

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

The description is long but information-dense, covering account prerequisites, sibling alternatives, tool mechanics, output characteristics, and performance expectations. Every sentence contributes meaningful guidance, but the single-paragraph wall-of-text format reduces scanability; bullet points or clearer section breaks would improve structure. Still, it is appropriately sized 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?

Despite the lack of an output schema, the description thoroughly explains what the tool returns: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', 'gaps[]', 'contradictions[]', and the `hop` field. It also covers prerequisites, alternatives, depth semantics, timing, and parsing behavior, making the description complete for an LLM agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%: both `question` and `depth` have detailed descriptions in the input schema. The tool description adds some contextual nuance (e.g., 'depth:"thorough" needs a paid plan' and 'second-hop iteration' details), but these largely mirror what the schema already states for the `depth` parameter. The `question` parameter is described similarly to the schema, so the description adds marginal value beyond the structured definitions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with a specific verb ('research'), a resource ('Pipeworx data sources'), and a distinctive mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL'). It also explicitly differentiates from siblings by emphasizing 'this is NOT open-web search' and contrasting with ask_pipeworx for single 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?

Usage guidance is explicit and actionable: 'For a single lookup use ask_pipeworx (one LLM call, not many)' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a conditional alternative: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' Depth-level guidance is also provided, explaining when to choose each depth setting.

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

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

Annotations already establish read-only and idempotent behavior. The description adds useful context beyond annotations: it returns top-N tools with full schemas and curated examples, is directly callable without a second lookup, and is intended as a first step. This enriches the agent's mental model without contradicting the annotation hints.

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

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

The description is somewhat long but well-structured: purpose in the first sentence, use cases in the second, output details in the third, and invocation priority in the fourth. Each sentence earns its place by providing distinct information, though it could be tightened slightly 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?

For a discovery tool with rich schema and annotations, the description is complete: it covers the purpose, when to use it, what results look like (names, descriptions, schemas, curated examples), and how to prioritize it. Even without an output schema, the description clearly communicates return shape and usage context, leaving no significant 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%, with aliases and examples for the query parameter and a limit parameter fully described. The description only says to describe the 'data or task,' which adds little beyond the schema's own 'Natural language description of what you want to do.' Thus the schema carries the load and the description provides no extra parameter-specific insight, fitting the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes itself from sibling tools by acting as a meta-tool that searches the available toolset rather than performing a domain-specific task.

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

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

Explicit usage guidance is provided: '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.' This tells the agent exactly when to use this tool versus direct domain tools, including a strong priority signal for initial exploration.

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

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

Despite strong annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: it fans out across multiple sources, returns specific data fields, includes fallback behavior (GDELT→GNews), notes soft-fail for patents, and describes URIs in output. No contradiction with annotations.

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

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

The description is long but information-dense; each clause contributes (examples, preference rule, sources, return fields, parameter hints). It could be better structured with line breaks, but remains scannable and front-loaded with purpose and usage.

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 present, the description carries the full burden of explaining return values. It does so explicitly: CIK + company name, recent filings with URIs, fundamentals fields, patents, news fallback, and LEI. It also covers parallel execution, constraints, and fallback behavior, making the tool's behavior and outputs well understood.

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

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

Schema coverage is 100% and the schema already documents both parameters, their types, allowed values, and the name-not-supported constraint. The description reinforces this with examples but does not add materially new semantics 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 opens with concrete example queries ('Tell me about X', 'research Acme') and clearly states the function: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from sibling tools by explicitly preferring this tool over chaining single-pack lookups and referencing resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states a clear exclusion: names are not supported and directs to 'use resolve_entity first if you only have a name.'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows it is a destructive, idempotent operation. The description matches the annotation but adds minimal extra behavioral context, such as permanent deletion or effects of missing keys.

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: the first states purpose, the second provides usage context. Every word earns its place, with no unnecessary detail.

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-key delete tool with strong annotations, the description covers what, when, and how it relates to siblings. No output schema is needed, and the description is fully adequate for agent 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?

The schema fully describes the 'key' parameter ('Memory key to delete'), and the description simply echoes 'by key'. With 100% schema coverage, the description provides no additional parameter semantics beyond the baseline.

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

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

The description uses specific verb 'Delete' with resource 'memory' identified by key, clearly distinguishing from sibling tools. It also names 'remember' and 'recall' as counterparts, reinforcing its unique role.

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

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

The description explicitly states when to use (stale context, task done, clear sensitive data) and mentions pairing with remember/recall. It does not explicitly provide exclusions or contrast with alternatives for other operations, 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds useful behavioral context: fetches the page, extracts info, emits standard markdown, output is a single text blob. No contradiction with annotations.

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

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

Two sentences plus a 'Useful for:' list. The main purpose is front-loaded, and every sentence adds value. No fluff or repetition.

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

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

No output schema, but the description explicitly states the output format ('standard llms.txt markdown format', 'single text blob ready to drop at site-root/llms.txt'). Covers purpose, usage scenarios, and output. Annotations handle safety. For a simple 2-param tool, this is 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 description coverage is 100%, so baseline is 3. The description mentions 'any URL' but does not add detail beyond the schema for max_links. The schema already fully defines both parameters.

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

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

Clear, specific verb+resource: 'Generate a production-ready llms.txt file'. Includes what it does (fetches page, extracts title/description/key links) and distinguishes from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation.

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

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

Provides concrete use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'). Does not explicitly exclude alternatives, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the series key format (B.{CURRENCY}.NOK.SP), business-day spot meaning, and the value interpretation (NOK per unit). 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 concise (two sentences) and well-structured, opening with the primary function followed by key details and examples. Every sentence earns its place without unnecessary fluff.

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

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

Given the tool's simplicity, a read-only lookup with fully covered parameters and no output schema, the description provides sufficient context: the meaning of the value, series key, and examples. It could mention handling of missing dates or other edge cases, but that is not critical for basic usage.

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 all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra semantic value by explaining the currency code examples and the series key, which helps clarify the purpose of the currency parameter and enhances understanding of last_n and period 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 clearly states the tool's purpose: fetching the latest (or last N) Norges Bank exchange rate for a currency against NOK. It names the specific resource (Norges Bank EXR series) and explains the value interpretation, effectively distinguishing it from generic series 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 clear context on when to use this tool (for NOK exchange rate queries) and includes examples of currencies. It does not explicitly mention alternatives or exclusions, but the purpose is specific enough that an agent would not confuse it with sibling tools.

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

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

The annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the key parameter's dot-separated format and wildcard semantics, which goes beyond the structured annotations and helps the agent use the tool correctly.

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

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

The description is concise and well-structured: it front-loads the primary purpose, explains the key syntax, provides two illustrative examples, and ends with a pointer to a related tool. Every sentence earns its place with no unnecessary filler.

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

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

With no output schema, the description could be expected to explain return values, but 'data fetch' implies the data is returned. The description covers the core usage, key construction, and flow discovery, making it sufficient for a generic fetch tool. Slightly incomplete regarding response format, hence a 4.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds examples and clarifies the key format, but the core semantic meaning is redundant with the schema. Baseline 3 is appropriate because the description doesn't significantly add meaning beyond the schema.

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

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

The description clearly states the tool's purpose as 'Generic SDMX data fetch from any Norges Bank flow', using a specific verb and resource. It distinguishes itself from siblings like get_exchange_rate by emphasizing its generic nature and provides concrete examples (EXR, IR).

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

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

The description gives clear usage context by explaining how to construct keys, providing examples, and pointing to list_flows for available flow references. However, it doesn't explicitly state when not to use this tool or mention specific alternatives for the same data-fetching purpose.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by specifying the exact content returned (dimension order, example series key, usage notes) and confirming the scope ('four flows available in this pack'). 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, efficiently structured sentence that leads with the action, specifies the scope, and lists the included data. Every phrase adds value—there is no filler or redundancy. It is concise while remaining 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 that the tool has no parameters, a rich annotation set, and no output schema, the description provides sufficient context for an agent to understand what the tool does and what it returns. It names the four flows, states the deliverable components (dimension order, example series key, usage notes), and is complete for a discovery/list tool.

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

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

The tool has zero parameters, and the input schema is empty with 100% schema description coverage. According to the rubric, 0 params gets a baseline of 4. The description does not need to explain parameters and correctly omits any parameter information.

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

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

The description uses the specific verb 'List' with a resource ('four Norges Bank SDMX data flows') and enumerates the exact flows (EXR, IR, GOVT_KEYFIGURES, GOVT_GENERIC_RATES). This clearly distinguishes it from sibling tools like get_series or get_exchange_rate, which retrieve specific data rather than listing available flows.

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 usage for discovering available data flows within the pack, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. For example, it does not say 'Use this before querying specific series' or contrast with get_series. The context is clear but the guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it returns specific fields (id, type, params, created_at, last_fired_at, fire_count), scopes to the caller's subscriptions, and defaults to active ones. This goes beyond the annotations without contradiction.

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

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

The description is two sentences, front-loaded with purpose, then return fields and use cases. There is no wasted wording; every sentence contributes to understanding the tool's purpose, output, and usage.

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

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

For a simple list tool with one optional parameter, the description covers what it does, the returned fields (despite no output schema), and when to use it. Annotations provide the safety and idempotency context. No critical information is missing for an agent to invoke it correctly.

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

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

The schema covers the sole parameter include_inactive with 100% coverage, so the baseline is 3. The description mentions 'active subscriptions,' which aligns with the parameter's default false, adding slight contextual meaning. However, it does not explicitly describe the parameter behavior beyond the schema.

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

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

The description clearly states the tool's action and scope: 'List the caller's active subscriptions.' This distinguishes it from sibling tools like subscribe/unsubscribe, which modify subscriptions, and list_flows, which lists flows. The verb 'list' and resource 'subscriptions' are specific and unambiguous.

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

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

The description gives explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call the tool relative to subscribe and unsubscribe. However, it does not explicitly name alternative tools or say when not to use it, which would push it to a 5.

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

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

The annotations are all false, providing no safety profile. The description compensates with rich detail: claim_token behavior, daily rate limit of 5, free/no quota consumption, and that the team reads digests daily. It also explains the follow-up mechanism for checking resolution status.

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

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

The description is longer than average, but every sentence serves a purpose—purpose, usage, exclusions, claim_token flow, rate limits. It's front-loaded with the core purpose and then explains constraints. Slightly dense, but justified.

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 all annotations false, the description carries full burden. It fully covers purpose, when/when-not to use, token handling, rate limits, and content guidance. Complete for a feedback tool.

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

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

Schema coverage is 100%, with detailed parameter descriptions. The description adds meaningful extra: clarifies when a claim_token is issued ('Filing without an account') and warns not to paste the end-user's prompt, which helps craft valid message content. This goes slightly beyond the schema.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This specific verb+resource ('tell... team') distinguishes it from sibling research/query tools, which are all about fetching or analyzing data.

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

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

Explicitly lists when to use: bug/feature/data_gap/praise, and explicitly says when NOT to use: for tools from a different MCP server, 'file it with that server instead.' This is excellent guidance with 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: caching (5min-1h), data source (CF analytics-engine), no PII, and self-aggregating signal. No contradiction with annotations; this is fully additive transparency.

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

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

The description is well-structured: a leading summary, a numbered list of use cases, and a final technical note. Every sentence adds value and contributes to the overall understanding without redundancy or filler.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description covers return content, use cases, caching behavior, privacy, and data provenance. There are no obvious gaps in what an agent would need to know 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% and includes the nuanced distinction between short and long windows. The tool description merely restates '24h, 7d, or 30d' without adding new semantic meaning, so the baseline of 3 applies.

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

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

The description uses a clear verb ('Returns') with specific resources ('top tools, top packs, and total call volume') over a time window. It distinguishes itself from siblings like discover_tools by emphasizing cross-agent aggregate behavior ('What other AI agents are calling'), 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?

Provides explicit use cases (hot data sources, canonical tool confirmation, use-case alignment) that tell the agent when to invoke it. However, it does not explicitly name when-not-to-use or alternative tools, so it falls one step short of the most explicit guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals important behavioral details: 'deviations >3pp emit a BUY/SELL EVERY LEG signal', 'partitions with >20% placeholder fraction return null arb signal', and the fill check behavior where 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It also explains rejected pairs via skipped_low_similarity and the response structure. This is rich, non-obvious behavior disclosed clearly.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode breakdowns. It earns its length by covering response format, edge cases, and actionable thresholds. A slightly tighter edit could remove some repetition, but the density is generally 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?

Despite having no output schema, the description fully covers what the tool returns (opportunities[], partition_check fields, fill_check results). It also covers behavioral edge cases, parameter formats, and cross-tool references (polymarket_fill_risk). Given the tool's complexity, the description is remarkably complete for an AI agent 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 coverage is 100%, so baseline is 3, but the description significantly enhances parameter meaning. For 'event', it gives examples ("fed-decision-may-2026") and explains it 'walks child markets... computes the partition_check'. For 'topic', it illustrates a seed question and explains cross-event scanning and Jaccard similarity anchoring. It also mentions that full Polymarket URLs are accepted for 'event'. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific resource (Polymarket) and the method (monotonicity violations, partition-sum). It also distinguishes modes (trending_scan, event, topic) and references related tools like polymarket_fill_risk, making it easy to differentiate from siblings.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a `trending_scan`', '`event` (recommended for a specific market)', and '`topic` (for cross-event scanning)'. It also guides toward an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is clear usage guidance with mode-specific recommendations and exclusions.

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

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

The description goes far beyond the annotations by revealing internal behavior: caching at the KV level keyed on knobs, response segmentation into three model families, diagnostic counters, and the 24h-move warning. It also explains that partitions always return kelly_fraction_half=0 at the parent level by design, and discloses the unreliability of Fed bets at meeting-month horizons. This is rich, non-contradictory behavioral transparency.

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

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

The description is dense and long but every sentence adds value. It front-loads the purpose in the first sentence and uses uppercase labels to structure segments, knobs, and diagnostics. While a bulleted format could improve scannability, the text is not wasteful and the level of detail justifies 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?

Given the complexity of 9 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains the three response segments, the diagnostic block (_diagnostics with funnel counters), the Fed-bet exclusion, and the caching behavior. An agent has enough information to understand the response shape and tool behavior without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema. For example, it explains that min_partition_leg_kelly applies per-leg because partition arbs always return kelly_fraction_half=0 at the parent level, and it elaborates on slippage_pp with a Polymarket fee note (zero fees, but bid/ask typically eats 20-50bp). This contextualization helps agents use the knobs correctly.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose as a daily 'what should I bet on today' discovery mechanism, which distinguishes it from broad market scanners. This is a distinctive purpose that differentiates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implicitly communicates when to use the tool (for discovering trading opportunities across top markets) but does not explicitly name alternatives or state when not to use it. The tradeable-edge knobs and Fed-bet handling give practical guidance, but no direct sibling comparisons are offered.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses extensive behavioral details: how snapshots are created (cache-miss), 60-day TTL limitation, the meaning of date gaps, computation on daily closes vs intraday, decay on |edge_pp_net|, negative sign indicating SELL YES, and the fate of expired opportunities. This is far beyond basic safety hints.

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

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

The description is long but well-structured with clear sections (purpose, Args, RESPONSE, LIMITS) and front-loaded intent. The length is justified because there is no output schema, so the detailed response breakdown is necessary. Minor redundancy exists in the Args section which repeats schema 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?

Since there is no output schema, the description fully compensates by detailing the response structure (tracked[] with trend and decay fields, expired[] with lifespan_days, snapshot_dates[]). It also covers data source, TTL limits, and calculation specifics, making the tool's behavior fully predictable.

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

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

The input schema already provides full descriptions for both parameters (days: lookback, default 14, clamp 2-30; window: 24hr | 1wk | 1mo, default 1wk). The description's 'Args' section merely restates this information without adding deeper semantics or usage nuances, so it adds no 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates from sibling tools like polymarket_edges by focusing on time-series persistence rather than current edge values.

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

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

The description provides clear context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' This implies using the tool to evaluate edge age and decay before trading. It does not explicitly name alternative tools or state 'when not to use', but the context is sufficient.

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

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

While annotations already indicate read-only/idempotent/non-destructive, the description adds substantial behavioral context: it walks the order-book ladder, returns specific fields for both modes, names legs likely to strand the user unhedged, and warns about the dominant loss mode. No contradiction with annotations exists.

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

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

Although long, the description is front-loaded with the core purpose and each sentence earns its place, covering modes, defaults, return values, and risk warnings. The use of SINGLE-MARKET/BASKET/USE THIS segments provides structure 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 tool with no output schema, the description is exceptionally complete, listing all return values for both modes, explaining edge cases like thin legs and forced directional risk, and placing it in workflow context relative to sibling tools. No critical information appears 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%, but the description goes well beyond the schema by interpreting size_usd differently per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), explaining the side default logic in basket mode, and clarifying the meaning of event/market slugs. This adds real value to parameter 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 opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the tool's function. It further distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as triggers, and by detailing both single-market and basket modes.

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

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

The description gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing the risk of thin-book overround not being capturable and partial basket fills converting arbs into unhedged directional positions.

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

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

Even with annotations already declaring read-only and idempotent behavior, the description adds substantial behavioral context: it explains compatibility_warning triggers, the meaning of matched_pairs:0 with skipped_cross_type, the temporal_alignment field and its implications, and the skipped_cross_type/subtype counters. This goes far beyond the annotations and fully discloses edge cases.

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 (~220 words) but well-structured with clear labels: TWO MODES, RESPONSE, SAFETY FIELDS, and a closing caution. It front-loads the core purpose and every sentence adds diagnostic or usage detail; however, it could be trimmed slightly without losing meaning, so it earns a 4 rather than a 5.

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

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

With no output schema, the description takes on the responsibility of explaining the response structure (leg-by-leg prices, matched spread, safety fields), and it does so thoroughly. It covers all the edge cases and gives concrete examples of non-equivalent bet shapes, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% description coverage, listing the same topic shortcuts. The description adds semantic value by explaining the two modes and how explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, which clarifies parameter relationships beyond the schema's field-level descriptions.

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

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

The description opens with a clear, specific statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further specifies two modes (topic shortcuts and explicit ticker/slug) and details the response, making it unmistakably distinct from sibling tools like polymarket_arbitrage by naming both venues and the spread concept.

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 clearly indicates when the tool is relevant (comparing the same resolving question across venues) and includes warnings about when the output is not meaningful, such as when compatibility_warning fires or temporal_alignment.aligned is false. It does not explicitly name alternative tools for other arbitrage scenarios, but it does say 'when bet shapes are equivalent that delta is a real signal' and that 'pre-mapped ≠ tradeable,' providing practical guidance on trusting results.

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

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

Despite annotations (readOnlyHint, idempotentHint, destructiveHint) already indicating a safe read operation, the description adds meaningful context: it is 'scoped to your identifier' and that the key is optional, enabling listing. This goes beyond the annotations and helps the agent understand data isolation and dual 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?

Three concise sentences lead with the main action, then add usage context and pairing hints. Every sentence carries weight, with no filler or repetition.

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

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

For a simple single-optional-parameter retrieval tool, this description is complete: it states the action, the use case, the scoping, and the relationship to sibling tools. The annotations already declare the operational safety, so the description needs no further elaboration.

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 description covers the 'key' parameter 100% (omit to list all). The tool description adds practical examples like 'the user's target ticker, an address, prior research notes' and reiterates the omission behavior, which strengthens comprehension beyond the schema alone. Though not essential, it provides useful semantic context.

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

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

The description states a specific action: 'Retrieve a value previously saved via remember, or list all saved keys'. This clearly distinguishes it from sibling tools like remember (save) and forget (delete), and includes the exact behavior of omitting the key to list all keys.

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

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

The description explains when to use it: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also points to sibling tools by saying 'Pair with remember to save, forget to delete.' However, it does not explicitly state when not to use it or list alternative lookup tools, stopping short of a 5.

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

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

The description directly contradicts the readOnlyHint annotation. It says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing operation, while readOnlyHint=true implies no persistent modifications. This is a severe inconsistency that undermines the agent's trust in the tool's safety profile. No other behavioral traits are disclosed beyond this conflicting mark_read 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 compact but information-dense. It front-loads the main purpose, then provides return structure, filtering options, read-state behavior, and an alternative access method. Every sentence earns its place, with no redundant or vague statements. It is well-structured for quick parsing.

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 adequately explains what the return payload contains (source, citation_uri, raw event payload). It covers filtering, since timestamp, mark_read behavior, and alternative access for scripts. Despite the contradiction, the description alone is complete for usage purposes, though the contradiction slightly undermines overall completeness.

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 beyond the schema. It gives a concrete example for the 'type' parameter (e.g. 'sec_8k') and explains the consequence of setting mark_read:true ('so the next call only shows newer ones'). This enhances the agent's understanding of parameter behavior beyond the bare schema descriptions, so it exceeds the baseline 3.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Pull fired events from your subscription feed.' It further distinguishes the tool by explaining it returns alerts written by the evaluator, which differentiates it from sibling tools like list_subscriptions or subscribe. The inclusion of return field details (source, citation_uri, raw payload) reinforces the purpose.

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

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

The description provides useful usage context: it explains polling works fine and points to an alternative REST endpoint for scripts and dashboards, implying when to use this tool versus an external alternative. However, it does not explicitly name or exclude sibling tools, so it falls short of a 5. The guidance on mark_read and filtering gives clear situational usage.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses rich behavioral details: it fans out to multiple external sources in parallel, includes a fallback chain, notes the PatentsView API sunset soft-fail, and details the return structure (changes[] grouped by source, total_changes, citation URIs). This gives the agent a clear mental model of execution 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 dense but well-organized. It front-loads user intents, then gives the core function, source fanout details, parameter format guidance, return shape, and an explicit alternative — all in one coherent block. Every sentence adds value; no fluff or repetition.

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

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

For a tool with no output schema, the description fully covers the return format (changes[] grouped by source, total_changes count, citation URIs). It also covers source fallback, soft-fail conditions, and when not to use the tool. Combined with high schema coverage and clear annotations, the context is complete for agent decision-making.

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 description need not repeat parameter basics. However, it adds valuable semantics: 'since' accepts ISO or relative shorthand with examples, 'value' accepts ticker or zero-padded CIK, and it recommends '30d' or '1m' for typical monitoring. This exceeds the schema-only information.

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

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

The description clearly states this is a change feed for a company over a time window, with a specific verb ('change feed') and concrete sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes itself from sibling tool entity_profile by explicitly directing users to that tool 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?

Provides explicit when-to-use examples ('What's new with X') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' Also explains fallback behavior (GDELT preferred, GNews on rate limit/5xx), leaving no ambiguity about when this tool is appropriate.

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

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

Beyond the annotations (which show a non-readonly, non-destructive, idempotent write), the description adds meaningful context: storage as a key-value pair scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. It doesn't disclose whether overwriting an existing key is allowed, but this is a minor gap given the idempotency hint.

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 with no wasted words: first states the core purpose, second gives usage guidance with examples, third explains storage mechanics and persistence. The most important information is front-loaded, and every sentence 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 two-parameter write tool with thorough annotations and full schema coverage, the description is complete. It covers purpose, usage triggers, storage semantics, retention policy, and sibling relationships, leaving no critical gaps for an agent 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 coverage is 100% and each parameter has clear descriptions and examples. The description reinforces the key-value concept but adds no new meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later' and explicitly positions it as a key-value store scoped by identifier. It distinguishes from siblings by pairing with recall (retrieve) and forget (delete), making the tool's role unmistakable.

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

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

The description gives explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples like resolved ticker and user preference. It also names recall and forget as complementary tools, though it does not explicitly state when NOT to use remember, so it falls just short of a 5.

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

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

Annotations already mark it read-only and idempotent, but the description adds crucial behavioral details: graceful degradation when GLEIF/OpenFIGI is unavailable, explicit listing of unresolved identifiers rather than omission, and the fact that each call cascades through multiple endpoints. This goes well 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 long but every sentence adds information, and it is front-loaded with example queries and the 'Use FIRST' directive. However, it is presented as a dense paragraph without bullet points, making it harder to scan; minor structural improvement would make it a 5.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior), the description is remarkably complete. It covers input forms, output identifiers, source labeling, unresolved handling, and even replaces manual lookups. With no output schema, it fully compensates by describing what the agent can expect.

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

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

Schema covers both parameters 100%, but the description enriches meaning with concrete examples (AAPL, 0000320193, 'ozempic') and explains what each entity type resolves to (CIK+ticker+LEI+FIGI for company; RxCUI+ingredient+brand for drug). This adds value beyond the schema's 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 explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers' with a clear verb and resource. It distinguishes itself by naming supported entity types (company, drug) and the outputs each returns (CIK, LEI, RxCUI), setting it apart from sibling tools that consume IDs.

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

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

It provides explicit guidance: 'Use FIRST whenever you have a name but need an ID,' along with sample queries ('What's the ticker for...', 'find the CIK for...'). It also clarifies type-specific input expectations (ticker/CIK/name vs. brand/generic drug), making it clear when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds valuable process detail: it probes each entity with ai_visibility_check, ranks by score, and returns a structured result with score, confidence, and signal density. This goes beyond the annotation claims and gives agents a clear mental model of what happens.

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

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

The description is three sentences with a clear front-loaded purpose. The second sentence explains mechanics (probing with ai_visibility_check, ranking, surfacing) and the third provides a practical use case and return format. No word is wasted, and every sentence 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?

Given the moderate complexity and full schema coverage, the description covers the core purpose, process, return structure, and typical use case. The only omission is the entity count range (2-8) and model requirements, but these are already in the schema descriptions, so the description remains sufficient for an agent to invoke correctly. A 4 is appropriate because it does not explicitly state limits, but the schema fills that gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it only implies entities are compared, but the schema already documents the 'entities' parameter including the first-as-subject convention. Models, _apiKey, and context are fully described in the schema, so the description does not need to compensate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It names the specific verb-resource pair and distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison rather than single-entity probing. The phrase 'ranks by score, surfaces which is most/least recognized' further clarifies the unique output.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' and gives an illustrative query. It implicitly distinguishes from ai_visibility_check by describing this as the multi-entity version, but it does not explicitly name alternatives or exclusion criteria. This is a minor gap, so not a 5.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds significant context about external API calls, partial failure degradation, the 5-30s latency for bundlephobia's first measurement, and the sources_failed field—information beyond the annotations that helps set expectations.

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 contributes value: purpose, usage triggers, output summary, ecosystem caveat, and failure behavior. The semicolon-separated field list in parentheses keeps the return summary compact and scannable.

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

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

With no output schema, the description enumerates the returned summary block fields, per-advisory detail, links, and recent alternative versions. It also covers operational caveats (performance, partial failures) and scope limitations, making it nearly complete for an agent 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 description coverage is 100%, and the schema already documents both the required package name and version defaulting behavior. The description does not add new parameter-specific semantics beyond reinforcing the composite nature, so 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 opens with a specific verb and resource: a composite check for adding an npm package, explicitly naming deps.dev and bundlephobia. It also states the ecosystem boundary ('NPM ecosystem only in v1'), which clearly distinguishes it from generic research 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 gives an explicit trigger: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion for other ecosystems (PyPI/Maven/Cargo/Go) and directs them to deps.dev:version directly, which is a clear alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond by disclosing the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and hard cap (200K chars, truncated and flagged). It also explains that each passage carries an offset for verbatim quote verification, which is crucial behavioral context.

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

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

The description is three sentences, each earning its place: purpose, usage guidance, and technical details. It is front-loaded with the core function and uses clear, scannable language. No fluff or repetition.

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

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

Given that there is no output schema, the description fully explains what the caller receives (top-N passages with character offsets and similarity scores) and the tool's limitations (200K char cap, truncation flag). It also provides real-world context (SEC 10-K, articles, long tool results) and integration guidance. The description is complete for a tool of this 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 description coverage is 100%, so the baseline is 3. The description adds minimal extra parameter semantics beyond the schema: it clarifies that 'text' is 'a fetched record' but doesn't elaborate on 'limit' or 'query' beyond what the schema already says. The example queries in the schema are sufficient, and the description doesn't significantly augment parameter 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 clearly states a specific verb+resource ('Semantic search INSIDE a fetched record') and details the input (text + query) and output (top-N passages with offsets and scores). It also distinguishes from siblings by referencing ask_pipeworx_grounded and by emphasizing that it searches inside already-fetched text rather than grounding over a whole document.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt', and explains the benefit (saves context, returns only relevant passages). It also pairs with a sibling tool, ask_pipeworx_grounded, giving a clear integration path. This provides both when-to-use and alternative 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, the description discloses auth requirements, supported subscription types with concrete examples, the always-on feed, and SMS verification/10-day caps. However, it omits the webhook delivery channel from the main enumeration even though the schema includes it, making the stated list of delivery channels incomplete.

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

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

The description is dense but well-structured, front-loading the core action and return value before elaborating on types and delivery. Some detail could be trimmed, but 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?

Given the nested schema and lack of an output schema, the description covers key operational aspects: auth prerequisites, return value, supported types, and delivery behavior. It falls slightly short by not mentioning the webhook option or the relationship to list_subscriptions/unsubscribe, but overall it is sufficiently complete for selection and invocation.

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

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

Schema coverage is 100%, and the description adds value by providing type-specific examples for params (sec_8k, polymarket_edge, fred_series) and concrete delivery-channel setups. It does not mention webhook in the main text, but the schema fully documents it, so the parameter semantics remain strong.

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 begins with a specific action ('Create a proactive monitoring subscription') and a targeted resource ('live-data event stream'), clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe. It also states the primary return value ('Returns the new subscription id'), making the purpose unmistakable.

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

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

The description provides clear context for when to use the tool: requires a Pipeworx OAuth account, creates a persistent feed, and references retrieval via recent_alerts or a registry endpoint. It does not explicitly name alternatives or state 'use this instead of X', but the scenario and delivery model imply appropriate use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context by explaining that results are drawn from a 'live catalog of thousands of tools' and that the output includes tool+argument shapes, which goes beyond what annotations convey. No contradictions with the annotations exist.

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 packed with information but well-structured: it opens with natural-language user intents, then states the core purpose, describes the output, and gives usage behavior. Every sentence earns its place, and the length is justified by the tool's onboarding role.

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

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

With no output schema, the description compensates by clearly describing the return format (category-bucketed example questions with tool + argument shape). It also covers parameter behavior, usage priority, and relationship to other meta-tools, making it complete for a simple one-parameter 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?

The schema already documents the `topic` parameter with a list of focus areas. The description adds value by providing concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it returns a 'full spread' versus focusing with a topic. This enriches the schema's basic enum description.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It explicitly differentiates this from sibling tools like ask_pipeworx and discover_tools by framing it as a 'first' action and referencing meta-tools to learn from.

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 this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools.' It also explains the no-argument default and the optional topic focus, giving clear context and alternatives.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context beyond these hints: ownership is enforced (only own subscriptions can be cancelled), and the row is deactivated rather than deleted, preserving historical events via recent_alerts. This transparency helps the agent understand the full lifecycle of the operation.

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

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

The description is two sentences, front-loaded with the action, and includes only necessary constraints and behavioral details. No wasted words.

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

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

For a simple single-parameter tool with no output schema and supportive annotations, the description covers purpose, usage constraints, and data lifecycle. It gives the agent enough information to invoke the tool correctly and understand the consequences.

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

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

The schema fully describes the only parameter (id as a uuid returned by subscribe), and the description merely restates 'by id' without adding further semantic detail. With 100% schema coverage, the description does not need to compensate, so the baseline 3 applies.

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

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

The description clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription). It distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on cancellation, 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 clear context for when to use the tool, including ownership enforcement and the deactivation behavior. It references recent_alerts for historical events, which is helpful, but it does not explicitly name alternatives for viewing or creating subscriptions (e.g., list_subscriptions, subscribe).

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

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

The description adds substantial behavioral detail beyond the annotations: it enumerates the possible verdicts, explains the distinction between 'could_not_verify' and 'unsupported,' and warns that 'could_not_verify' carries a verification_error and must not be treated as evidence. This is valuable for callers and goes far beyond the readOnly/idempotent hints. No contradiction with annotations exists.

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

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

The description is well-structured with a clear intro, route breakdown, return summary, and important caveats. Although it's longer than average, every sentence earns its place by providing critical details (verdict semantics, error handling, routing, efficiency benefit). It is front-loaded with user intent phrases and maintains readability.

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

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

For a tool with no output schema and rich annotations, the description is remarkably complete. It covers return values, verdict meanings, error cases, source routing, citation format, and even why it replaces multiple steps. There are no significant gaps for a caller to understand what the tool does and how to interpret its response.

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?

While the schema already documents both parameters at 100% coverage, the description enriches them: it gives concrete claim examples and clarifies that tolerance_pct overrides implied wording tolerance, with a specific use case for hallucination detection. This far exceeds the baseline for high schema coverage by adding usage nuance and constraints.

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

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

The description clearly states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It lists trigger phrases like 'fact check' and 'verify the claim that,' making the tool's purpose unmistakable. It also distinguishes its behavior from generic search by explaining the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others), which differentiates it from sibling tools like 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?

It explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct.' It further specifies the scope (company-financial vs. any other factual claim) and notes that it replaces multiple sequential calls, which helps the agent decide when to invoke it instead of orchestration. This is clear when-to-use guidance, though it doesn't enumerate exclusions, the routing rules provide strong context.

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