Bank Of Canada

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context: the default model is free, Anthropic requires a BYO key with direct payment to Anthropic, and the return format is specified. It does not contradict annotations.

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

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

The description is three sentences, with the core function in the first sentence, configuration details in the second, and use cases in the third. Every sentence adds value, and it is front-loaded with the most important information. 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?

There is no output schema, so the description takes on the burden of explaining return values, which it does clearly: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also covers configuration options and use cases, making it complete for a multi-model probe tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds a bit of extra meaning (e.g., 'pass _apiKey to also probe Anthropic' and 'omit for just workers-ai') but does not significantly expand beyond the schema. This matches 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 opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or deep_research, which focus on asking questions or researching rather than scoring AI visibility.

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 AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and how to enable Anthropic, but it does not explicitly state when not to use it or name alternatives, so it falls short of a full 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining routing behavior, citation URIs, 'one fast call', and tier availability. It does not contradict any annotations, though it omits potential failure modes or rate limits, so it's not a perfect 5.

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

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

The description is lengthy but front-loaded with the key priority ('PREFER OVER WEB SEARCH') and packed with actionable details, examples, and exclusions. Every sentence earns its place, though it could be slightly tightened to reduce the wall-of-text effect.

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 broad default router with many domains, the description is comprehensive: it covers domain categories, example queries, output format (structured answer with citations), speed, and explicit substitution guidance for more specialized tools. No output schema exists, but the description adequately characterizes the return value.

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 (five aliases plus question) documented. The description doesn't add parameter-specific semantics, but the schema already adequately clarifies the single 'question' parameter in natural language. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,564 tools across 1462 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its scope 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH...', 'Use whenever the user asks...', 'START HERE for most questions', and 'Step up only when needed' with specific alternative tools and their use cases. This leaves no ambiguity about when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context about live candidate testing, result comparison against the stable router, and reassures that 'this IS a full working router' despite the beta label. No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the most important distinction, and each sentence adds necessary context. Slightly wordy in the middle, but no filler or redundancy.

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

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

Given the tool is a beta variant, the description adequately covers its identity, current state, usage, and relationship to the stable version. It references the response shape without detailing it, which is acceptable since no output schema exists and it mirrors ask_pipeworx.

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

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

The input schema covers all six parameters with descriptions, including aliases, achieving 100% coverage. The description merely repeats 'same arguments' without adding new semantic detail, so the baseline score 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 explicitly identifies this as a beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape. It clearly distinguishes from the stable sibling tool by noting 'candidate routing improvements' and experimental status.

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 states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains current state ('No candidate is active right now'). It lacks explicit exclusions or comparison with ask_pipeworx_grounded, but the guidance is clear enough for selection.

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

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

Although annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial context beyond those: exact success shape, evidence requirement, refusal reasons, and the cost tradeoff of an extra LLM call. None of this contradicts the annotations, and it fully explains what happens when data does not directly answer.

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 concept ('Hallucination-resistant answer mode for high-stakes reads') and every subsequent clause adds essential operational detail: routing, answer extraction, return formats, refusal reasons, use cases, and cost tradeoff. Despite its length, there is no filler or redundancy.

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

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

For a complex tool with no output schema, the description fully covers return values, failure modes, cost implications, and when to prefer it over a sibling. It is complete enough for an agent to invoke it correctly and interpret both success and refusal responses.

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

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

Schema coverage is 100% for the one required field, question, and its aliases, so the schema already carries param meaning. The description adds general context about natural language routing and filling arguments but does not add syntax, formatting, or semantic details beyond what the input schema provides; a 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 identifies a specific, differentiated tool: a hallucination-resistant answer mode for high-stakes reads that routes like ask_pipeworx but extracts answers only from tool results. It distinguishes itself from siblings by emphasizing grounded evidence and explicit refusal behavior, leaving no doubt about what the tool does.

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

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

The description gives explicit when-to-use guidance: use whenever an answer will be quoted, cited, or acted on and facts must not be invented, with examples like financial verdicts, legal claims, medical lookups, and public statements. It also names the alternative, ask_pipeworx, and recommends it for casual lookups, while noting the extra LLM call cost.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes far beyond that. It discloses low-confidence short-circuit behavior, closed-market handling, wide-spread illiquidity flags, cancellation-rule parsing (refund_50_50, resolves_no_on_cancel, etc.), and news-fallback retry behavior with _fallback_attempted and retry_after_sec. This rich behavioral context is exactly what agents need and is not contradicted by 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 well-structured with CAPITALIZED section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Every section adds operational detail for a complex tool, though it could be more concise by trimming some fan-out examples. Overall it earns its length.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers result.market, result.analysis, result.evidence, parent_event, news fields, safety short-circuits, and resolution-rule risks. Edge cases like market_closed_or_inactive and illiquid_wide_spread are all documented. This is a complete picture 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?

The input schema provides 100% description coverage for all three parameters, including the market slug/URL/question-text formats, depth enum, and include_raw behavior. The tool description does not add additional parameter semantics 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 opens with a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from siblings by describing the full pipeline (resolve, classify, fan-out, compare) and stating explicit use cases like "should I bet on X" and "is there edge in Z", which differentiates it from tools like polymarket_edges or validate_claim.

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 provides examples of query formats. However, it does not explicitly contrast with alternative tools or state when not to use it, so it lacks the 'exclusions' component for 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), sorting behavior by primary metric, and the return format of paired data with citation URIs. This is rich 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 dense but not bloated; every sentence contributes specific value. It front-loads example phrases and key behavior (parallel call, data sources, sorting). Slightly longer than minimal, 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?

With no output schema, the description adequately explains return format (paired data + citation URIs), sorting, and data sources. It also addresses edge cases like off-calendar fiscal years. For a tool handling 2–5 entities and two types, 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 coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining that type='company' pulls 10-K revenue/net income/cash/debt, while type='drug' pulls FAERS/adverse-event counts, and by providing concrete examples for the values array (e.g., tickers like AAPL, drug names like ozempic).

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

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

The description precisely defines the tool as a side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete example queries like 'X vs Y' and 'rank these companies.' It clearly distinguishes from sibling tools by emphasizing the parallel call design versus sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong when-to-use directive. It also differentiates by entity type (company vs drug), describing the specific data each type pulls, which guides tool selection.

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

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

Annotations already indicate read-only/non-destructive, but the description adds extensive context: account and paid-plan requirements, 15-60s latency (90s for thorough), parallel routing to 5,564 tools, gaps[] for unanswered facets, contradictions[] for disagreeing findings, citation_uri semantics, and semantic excerpting behavior.

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

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

The description is long but each sentence adds unique value (account, capabilities, alternatives, depth semantics, output format, latency). It is dense rather than rambling, though a single-paragraph structure could be improved with bullets; still, content 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?

No output schema exists, so the description fully explains the return format: findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]. It covers auth, latency, limitations (not open-web), and depth variants, making it exceptionally complete for a complex tool.

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

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

Schema coverage is 100% with good param descriptions. The description adds value beyond the schema by explaining the account tier needed for depth='thorough', providing example question formats, and elaborating on how depth affects hops, gap recovery, and contradiction scanning.

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

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

The description explicitly states the tool performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' by decomposing questions and routing to tools in parallel. It clearly differentiates from siblings by stating 'this is NOT open-web search' and contrasts 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?

Provides explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead'; 'Best for broad/multi-part questions over structured data'; 'For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. Also details depth-level usage scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas' and 'each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by explaining the return format and readiness, though it does not mention rate limits or 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 structured with a clear purpose statement first, followed by usage context, return details, and a usage directive. It is somewhat long due to the enumerated list of data domains, but each item is informative and helps the agent understand scope. No sentences are wasted.

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

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

For a discovery tool with no output schema, the description adequately covers what it does, when to use it, and what it returns. It lacks explicit mention of edge cases or error handling, but given the tool's simplicity and the strong annotations, this is sufficient 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 description coverage is 100%, and each parameter (query, limit, and aliases) is documented in the schema. The description mentions 'top-N' which maps to the limit parameter, but does not add meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes itself from siblings by being a discovery/meta tool. The enumeration of domains (SEC filings, FDA drugs, etc.) further clarifies scope.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and an explicit rule for when to invoke it, while hinting that for a specific known answer, you'd use the relevant tool directly.

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

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

Beyond the annotations (read-only, idempotent, etc.), the description discloses important behavioral traits: it fans out to multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), notes the USPTO PatentsView API sunset and its soft-fail behavior, and mentions the GDELT→GNews fallback for news. It also specifies output contents (filings, fundamentals, patents, LEI), which gives the agent a clear picture of what to expect.

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

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

The description is lengthy but densely packed with useful information: examples, rationale, return details, and limitations. It is front-loaded with user-phrase examples that help the agent recognize intent. While some example phrases could be trimmed, every sentence contributes to operational guidance, making it acceptably concise for the tool's complexity.

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

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

Given the tool's multi-source complexity and lack of an output schema, the description thoroughly explains what data is returned (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and notes key caveats (USPTO sunset, name unsupported). It provides enough context for an agent to invoke the tool correctly and interpret its results, 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?

The input schema already provides comprehensive descriptions for both parameters (type and value), including examples and the 'names not supported' caveat. The description adds little beyond reinforcing these examples (AAPL, 0000320193) and the requirement to use resolve_entity for names. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states this tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb (profile/brief) and resource (company), and explicitly distinguishes from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is requested. The numerous example queries reinforce the intended usage.

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 instead of chaining multiple single-purpose lookups for holistic company research. It also clearly states a limitation (names are not supported) and directs the agent to resolve_entity first if only a name is available, offering a concrete 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 disclose destructiveHint=true and readOnlyHint=false, so the core safety profile is known. The description adds minimal extra behavioral detail, though it does mention clearing sensitive data, which provides some context beyond the schema.

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 short sentences, front-loaded with the core action, followed by usage scenarios and sibling references. Each sentence adds value, with no redundancy or 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 destructive tool, the description covers purpose, usage, and related tools. Annotations address safety, and the absence of an output schema is acceptable for a delete operation as the effect is straightforward.

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 the property description 'Memory key to delete' already clear. The description merely repeats the 'key' concept without adding syntax, format, or additional semantic detail, so a 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 uses a specific verb 'Delete' with a clear resource 'previously stored memory' and the mode 'by key'. It distinguishes from sibling tools by explicitly pairing with 'remember and recall', making its role unambiguous.

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

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

The description provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. It also names related tools to pair with, offering practical guidance for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description need only add process detail. It does so by disclosing the fetch-and-extract behavior and the output as a text blob, which is consistent with the annotations.

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

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

Three sentences deliver purpose, process, output, and use cases without extraneous detail. Front-loaded with the primary verb and resource.

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

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

Given the simple two-parameter schema and strong annotations, the description covers all essential aspects: what it does, how it works, output format, and practical uses. No output schema exists, but the return format is described as a text blob.

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 (url and max_links) with descriptions, and the tool description does not add further parameter semantics. Baseline of 3 applies since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It lists specific actions (fetch, extract, emit) and the output format, making it distinct from likely sibling tools like ai_visibility_check.

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 ('getting a client's site indexed by AI, drafting llms.txt, or auditing a competitor') which define clear contexts for use. Does not name alternative tools or exclusions, but the scenarios are sufficient for general guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds the 'in one call' batching behavior and an example group, but does not disclose output format or pagination. This is adequate but not rich.

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

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

The description is three concise sentences: main purpose, useful group example, and parameter mode. It is front-loaded with the primary function, and every sentence adds value without padding.

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 4-parameter read-only tool with rich annotations and no output schema, the description provides core purpose, a concrete example, and parameter selection guidance. It lacks explicit return-format details, but the purpose implies observations, making it sufficient for 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds a hint about choosing between recent and date-window modes and provides a useful group value, but this only slightly extends 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 clearly states the tool returns observations for every series in a named group in one call. This distinguishes it from per-series observation tools and the concrete example 'FX_RATES_DAILY' reinforces the scope.

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

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

It provides clear context: use this when you need observations for all series in a group. It also gives a useful group example and parameter guidance ('Use recent=N or a start_date/end_date window'). However, it does not explicitly name alternatives like get_observations for single-series queries.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context by listing well-known series identifiers and the choice between recent observations or date-range windows. It also implicitly communicates the mutual exclusivity of the two modes, supplementing the annotation coverage.

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

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

The description is three sentences, front-loads the core purpose, then immediately gives concrete examples and parameter options. Every sentence earns its place, and there is no redundant or vague wording. This is a model of concise structure.

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-like tool with 4 parameters and no output schema, the description covers the core purpose, gives concrete series examples, and outlines both usage modes. It could mention the return format or error handling, but the tool is straightforward and the schema fills remaining parameter details, making this sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces comma-separated series names and provides practical examples, but it does not add new semantic meaning beyond what the schema already documents, such as precedence rules or date formats. The examples are helpful but not essential.

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

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

The description clearly states the tool retrieves time-series observations for Bank of Canada series, with specific examples (FXUSDCAD, V39079). This goes beyond the generic name and distinguishes it from list_series or series_info, which cover metadata rather than observations.

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 the two primary usage modes (recent=N vs start_date/end_date) and clarifies that series names must be comma-separated. However, it does not explicitly contrast with sibling tools like get_group_observations or list_series, so the when-to-use guidance is only implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral detail about case-insensitive substring matching against label/description, which goes beyond the annotations.

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

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

The description is two short sentences with no wasted words. The main purpose is front-loaded, and the filtering detail is compactly presented.

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

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

For a simple read-only list tool with no required parameters and no output schema, the description adequately explains what it does and how to filter. It omits return format details, but these are not critical for such a straightforward 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%, with both 'limit' and 'query' described. The description provides an example ('exchange', 'lending') and mentions case-insensitivity, but this largely overlaps with the schema, adding minimal extra semantic value.

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

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

The description clearly states the tool 'Discover available series groups' with a specific verb and resource. It also describes the filtering option, distinguishing it from sibling tools like list_series which focuses on series rather than groups.

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: use this tool to discover available series groups, optionally filtering by a substring. It doesn't explicitly mention alternatives or when not to use it, but the usage context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds the useful caveat that listing all series without a query returns a large result set, and it clarifies the case-insensitive substring matching behavior. This goes beyond the structured 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?

Three short sentences front-load the action ('Discover available series'), provide an example, and warn about the unfiltered case. 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?

The tool is simple (two optional params), annotations are rich, and schema covers all parameters. The description adequately explains the tool's behavior and the volume caveat, making it complete for an agent to invoke correctly.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description reiterates the query parameter's purpose but adds no additional syntax or format details 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 uses a specific verb 'Discover' and names the resource 'series', clearly distinguishing it from siblings like series_info (which likely targets a single series). The optional filter behavior is also stated, making the purpose immediately understandable.

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 the optional query filtering and warns that omitting the query returns all series ('large'), providing clear usage context. However, it does not explicitly mention alternatives or when not to use this tool, so it earns a 4 rather than 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 destructiveHint, so the safety profile is known. The description adds caller scoping and return field details but no major behavioral traits beyond what annotations offer. The 'active' wording hints at the default but doesn't mention the include_inactive option, which is in the schema.

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

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

Two sentences, front-loaded with the core purpose and return fields, followed by a single practical usage sentence. 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 list tool with no output schema, the description covers the purpose, return fields, and usage context. The only gap is the unmentioned include_inactive parameter, but that is fully covered by the schema, so the description is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100%, with the single parameter include_inactive fully described. The description does not mention this parameter, so it adds no extra semantic value beyond the schema, which is acceptable per 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 opens with 'List the caller's active subscriptions', which clearly states the verb and resource. It distinguishes from siblings like subscribe and unsubscribe by focusing on listing. It also enumerates the returned fields, adding specificity.

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

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

The second sentence gives explicit use cases: 'review what you're monitoring before adding more' (before subscribing) and 'find an id to cancel' (before unsubscribing). This is clear context, though it does not explicitly name alternatives or state when not to use the tool.

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

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

Annotations are all false (no read-only, idempotent, etc.), so the description carries the burden. It discloses the claim_token flow (filing returns a token that can be used later to check status), rate limiting (5 per identifier per day), cost (free), and that the team reads digests daily. 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 front-loaded with the purpose and usage. Every section (exclusions, token handling, rate limits) serves a purpose, though some redundancy exists ('ONLY for tools served by this Pipeworx connection' and 'Not sure? Pipeworx tool names are the ones this connection lists'). Compact enough but slightly verbose.

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

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

No output schema, so the description explains the return behavior: filing returns a claim_token, and re-invoking with that token reads status and updates. It also covers rate limits, cost, and alternatives for non-Pipeworx tools. This is a fully specified feedback tool given its simplicity.

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

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

Schema covers all parameters at 100%, so baseline is 3. The description adds value by explaining the claim_token parameter's lifecycle (pass it back later to read fixes) and reinforcing context structuring. This lifts it above baseline, though other parameters (type, context, message) are already well described in 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings by listing concrete use cases (bug, feature/data_gap, praise) and explicitly contrasts with query tools like ask_pipeworx.

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

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

Provides explicit 'Use when...' scenarios and a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also advises on how to frame feedback (describe in terms of Pipeworx tools/packs, not end-user prompts), giving actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds non-obvious behavioral details: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This goes beyond the annotations to inform the agent about data freshness, privacy, and source, which is valuable 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 somewhat lengthy but well-organized: it opens with the core value proposition, lists use cases in a numbered format, and ends with data provenance and caching details. Every section adds useful context, though the use-case list could be slightly tightened without losing value.

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

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

The tool is simple (one optional parameter with enum), and the description fully explains its output ('top tools, top packs, total call volume') and behavior (cached, no PII) without an output schema. It provides enough context for an agent to select and invoke the tool correctly, and its use cases cover the main scenarios.

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 only parameter (window) with an enum and description. The tool description adds marginal nuance by explaining that shorter windows surface 'what's hot right now' and longer windows show 'steady-state demand,' but this largely mirrors the schema's description. The baseline of 3 applies because schema coverage is 100%.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This distinguishes it from sibling tools like discover_tools by specifying it reveals aggregated usage by other agents, not a general discovery mechanism.

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

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

The description lists three specific use cases: discovering hot data sources, confirming canonical tool choice, and aligning with typical agent needs. This provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative 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?

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial behavioral context: the >3pp threshold for partition deviations, the semantic-anchor Jaccard similarity rule, the placeholder-fraction filter that can null the signal, and the fill-check behavior that may conclude a signal is not tradeable. It also discloses that it returns null signals in certain cases, which is not in the annotations. No contradiction.

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

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

Although long, the description is structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and every sentence carries unique actionable information. It is front-loaded with the core purpose in the first sentence, and uses labels to make scanning easy. There is no redundancy or filler.

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

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

Given the tool's complexity (multiple modes, subtleties like placeholder filtering and fill checks) and the absence of an output schema, the description covers not only the input semantics but also the response structure (opportunities[], partition_check, fill_check fields) and safety guidance (do not trade if realizable_edge_pp ≤ 0). This is fully commensurate with the tool's complexity.

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

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

Schema coverage is 100% but the description significantly enriches both parameters: for 'event' it explains that the tool walks child markets and checks date/threshold ordering plus partition sum; for 'topic' it describes cross-event flattening and the comparator. It also documents the no-arg behavior even though no parameter is required, adding semantics beyond the schema.

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

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

The description opens with a specific verb+resource+method: "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks." It clearly distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by naming the detection techniques and modes. It also states the three invocation modes (no-arg, event, topic), making the tool's scope explicit.

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

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

The description provides explicit when-to-use guidance: "Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan." It recommends event mode for specific markets and even names alternatives: "For custom sizing use polymarket_fill_risk" and warns when not to trade (realizable_edge_pp ≤ 0). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context beyond that: the 1-hour KV cache keyed on all knobs, the note that Fed bets are excluded due to unreliable signal, the explanation of how tradeable-edge knobs drop opportunities, and the diagnostics funnel showing why segments may be empty. It also discloses the model assumptions and caps (e.g., Kelly capped at 0.25). No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then organized into clear labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). The structured format makes the dense content scannable, and there is no redundant repetition of the schema.

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

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

Given 9 parameters, no output schema, and high complexity, the description is remarkably complete. It describes the response top-level fields (by_segment, fed_candidates, _diagnostics), explains the filters and their intended use, and even discloses caching behavior. The Fed note addresses a subtle edge case. This is sufficient for an agent to confidently invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how parameters interact (e.g., min_partition_leg_kelly applies per-leg because parent-level kelly_fraction_half is always 0 for basket trades; min_liquidity and max_spread_pp are 'tradeable-edge filters'). This goes beyond the schema descriptions and helps the agent reason about parameter effects.

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 further clarifies the intended use case — 'what should I bet on today' — and distinguishes the tool from generic market scanners by detailing its three model-family segments and the built-in edge calculation. This clearly separates 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 states a clear context: it surfaces opportunities without paging hundreds of markets and is aimed at discovery. It also explains specific usage knobs like min_liquidity/max_spread_pp and min_partition_leg_kelly. However, it does not explicitly name alternative tools for different scenarios (e.g., use polymarket_edge_tracker for tracking, polymarket_fill_risk for execution risk), so it lacks overt exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description goes far beyond that by detailing the response structure (tracked[], expired[], snapshot_dates[]), data TTL limits, snapshot gap semantics, and the sign convention for edge_pp_net. It adds rich behavioral context without contradicting the annotations.

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

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

The description is long but excellently structured with clear sections (Args, RESPONSE, LIMITS). Every sentence provides substantive information, including a motivating example, output field explanations, and limitations. It is front-loaded with purpose and not bloated.

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

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

For a tool with no output schema, the description is exceptionally complete: it specifies all return fields, their meanings, data freshness caveats, TTL constraints, and even how snapshot gaps occur. It covers all necessary context for an agent to use the tool correctly.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description's param details ('default 14, max 30', 'snapshot family') mostly restate the schema's existing descriptions and do not add meaningful semantic depth beyond what is already structured.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question ('how long has this edge existed and is it shrinking?'). It explicitly distinguishes itself from the polymarket_edges tool by being built from its snapshots, making the purpose unambiguous and differentiated 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?

It gives clear context on when to use the tool (evaluating whether a wide edge is fresh vs. stale) and implies it is for persistence analysis rather than current-edge queries. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already provide readOnly/idempotent/non-destructive info; the description adds rich behavioral context: ladder walking, return fields, partial basket fill converting arb into unhedged directional risk, and the default side auto-selection logic. 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 well-structured with mode labels and a clear front-loaded core purpose. Almost every sentence contributes new information; mild verbosity 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?

No output schema exists, but the description enumerates all return fields for both modes, states prerequisites, default values, clamp ranges, and critical risk warnings. This gives an agent everything needed to invoke 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?

Despite 100% schema coverage, the description adds meaning: size_usd differs between single-market (max spend/target proceeds) and basket (settlement notional per leg), side defaults vary by mode, and the required relation between market/event and mode is clarified.

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.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the two invocation modes (single-market vs basket) and prerequisites.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description thoroughly discloses behavior: it explains compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It also states that most pre-mapped topics return warnings, setting expectations for what the tool will actually produce.

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

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

The description is lengthy but well-structured, front-loading the purpose and modes before diving into response fields and edge cases. Each sentence adds necessary detail for a complex tool, though it could be slightly condensed without losing value.

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

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

Despite lacking an output schema, the description defines the response shape (leg-by-leg prices, matched spread top_spreads_pp) and explains safety fields, temporal alignment, and warning conditions. This gives the agent a complete picture of the tool's outputs and failure modes.

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% parameter coverage with detailed descriptions, including the topic list and override semantics. The description repeats this information without adding new parameter-level details, 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating the tool's specific verb and resource. It distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison and explicitly describing two operation 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?

It provides explicit guidance on when the tool is appropriate, noting that 'Real cross-venue spreads are rarer than the macro-shortcut list suggests' and warning that 'pre-mapped ≠ tradeable.' However, it does not name alternative tools or give explicit when-not guidance, 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 declare safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context beyond annotations: scoping to agent identifier (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieving a specific key versus listing all keys when argument omitted. 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 compact (3 sentences) and front-loaded: first sentence defines the action, second gives typical usage, third clarifies scope and companions. Every sentence earns its place with no redundancy or fluff.

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

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

For a tool with one optional parameter and no output schema, the description is complete: it covers the action, use cases, scope, and relationships to sibling tools. An agent can confidently decide when to invoke this tool without additional context.

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

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

Schema already covers the sole parameter with 100% coverage ('Memory key to retrieve (omit to list all keys)'). The description reinforces this by explicitly mentioning the omit behavior and providing concrete examples of key values (ticker, address, research notes), adding practical 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: 'Retrieve a value previously saved via remember, or list all saved keys' with specific verbs and resource. It distinguishes itself from sibling tools by naming its companions 'remember' and 'forget' and by explaining it avoids re-deriving context from scratch, setting it apart from research/derivation 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?

Explicitly says when to use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' Also names companion tools ('Pair with remember to save, forget to delete') giving clear alternatives for related operations.

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 explicitly states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones,' which is a state mutation. However, the annotations declare readOnlyHint=true, implying no side effects. This contradicts the described behavior and is a serious inconsistency. The description itself is transparent about the mutation, but the annotation misleads the agent about the tool's side-effect profile.

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 appropriately sized with no filler. It leads with the core purpose, then covers return value, parameters, and usage context each in a sentence or two. Every sentence adds value, and the structure is easy to scan.

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

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

The description covers return value details, parameter usage, and even alternative access, which is good for a tool with no output schema. However, the contradiction with the readOnlyHint annotation creates confusion about side effects, and there is no mention of what happens with unread_only or limit defaults beyond the schema. The tool is complete in content but is undermined by the annotation mismatch.

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 all parameters (100% coverage), but the description adds meaningful context: it gives an example for 'type' (sec_8k), explains the semantics of 'since' as an ISO timestamp, and clarifies the behavior of 'mark_read' and its effect on subsequent calls. This goes beyond simply restating parameter names and provides practical usage insight.

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 verb-resource combination: 'Pull fired events from your subscription feed.' It goes on to specify the return value (source, citation_uri, raw event payload) and distinguishes itself from sibling tools like list_subscriptions or recent_changes by focusing on fired alerts in the feed.

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

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

The description provides context for usage, including it is for the persisted feed, supports filtering by type and since, and mentions that polling works fine. It also offers an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards, which implies when the tool might not be needed. It does not explicitly compare to other tools, but the guidance 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 and idempotentHint, and the description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT preferred, GNews on rate-limit/5xx), and soft-failure of USPTO due to the PatentsView API sunset. It also discloses the return structure including citation URIs, exceeding the annotation coverage.

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

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

The description is dense and front-loaded with purpose, followed by source details and alternative direction. While it has many clauses and embedded examples, every sentence contributes distinct information with no fluff. It is slightly longer than necessary but well-structured.

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 adequately covers return values (changes[], total_changes, citation URIs) and explains multi-source fan-out, fallback behavior, and soft-failure. It also provides parameter formatting and sibling differentiation, making it fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly reiterates what the schema already states for 'since' and 'value', with only minor additions like typical monitoring window suggestions ('30d' or '1m'). These do not significantly deepen parameter understanding beyond the schema.

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

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

The description clearly identifies the tool as a 'change feed for a company' with a specific verb and resource, and it lists concrete sources (SEC EDGAR, GDELT→GNews, USPTO). It also explicitly distinguishes itself from sibling 'entity_profile', resolving potential ambiguity.

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

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

The description provides explicit when-to-use guidance (e.g., natural language queries like 'What's new with X') and an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also offers practical parameter advice like using '30d' or '1m' for typical monitoring.

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

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

The description discloses key behavioral traits beyond the annotations: memory is scoped by identifier, persistence differs for authenticated (persistent) vs anonymous (24 hours) users, and it stores key-value pairs. This adds useful context that the annotations (readOnlyHint, idempotentHint, destructiveHint) do not cover, 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 purpose, then usage context, then storage details. Every sentence contributes meaning, with no redundancy or fluff.

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

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

For a simple write tool with no output schema, the description covers all essential aspects: purpose, when to use, persistence behavior, and relationship to sibling tools. The lack of return value details is acceptable given the tool's simplicity.

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

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

The schema description coverage is 100%, with both key and value parameters clearly described and example values provided in the schema. The description adds no additional parameter semantics beyond what the schema already offers, 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 clearly states the tool's purpose: to save data the agent will need later. It uses specific verbs ('Save data') and provides concrete examples of what to store (ticker, address, preference, research subject). It also distinguishes itself from sibling tools by explicitly referencing recall and forget as complementary operations.

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 the tool: 'Use when you discover something worth carrying forward' and provides examples. It also names the alternatives for retrieval (recall) and deletion (forget), making the decision boundary clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, but the description adds valuable behavioral details: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, and explicitly lists unresolved identifiers rather than omitting them. No contradiction with annotations; the description enriches the safety and behavior profile.

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 examples and a clear usage guideline, but the detailed breakdown for company type (cross-source identity spine, graceful degradation) is somewhat verbose. While every sentence adds value for a complex tool, the length reduces conciseness slightly. Still well-structured and to the point for the intended purpose.

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

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

Given the tool has 2 parameters and no output schema, the description is remarkably complete. It covers input formats, supported entity types, resolution sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation, and output behavior (unresolved identifiers listed). The agent can confidently select and invoke this tool based solely on the description.

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

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

Input schema has 100% description coverage, but the description significantly adds meaning: it explains that the 'value' parameter accepts ticker, CIK, ISIN, or name for company; brand or generic name for drug; and details what identifiers each type returns (e.g., CIK, LEI, FIGI for company; RxCUI for drug). This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool resolves names to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It differentiates from siblings like entity_profile by positioning itself as the first tool to use when you have a name but need an ID, and it emphasizes that it replaces multiple manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context for when to invoke this tool. It explains the supported types and what inputs are accepted, but does not explicitly mention when not to use it or name specific sibling alternatives for different tasks, though the context is strong enough for an agent to infer usage boundaries.

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=true, idempotent=true, and destructive=false, so the safety profile is covered. The description adds valuable behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns specific fields. This is more than just restating annotations and gives the agent a mental model of what happens during invocation.

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 and front-loaded, with the main verb and purpose in the first sentence. Each subsequent sentence adds unique value (implementation detail, use case, output format). The example quote is a nice touch that clarifies intent without being verbose.

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

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

There is no output schema, so the description appropriately explains what will be returned (ranked list with score, confidence, signal density). It also covers the core behavior and use case. It does not mention configuration options like models or _apiKey, but those are fully documented in the parameter schema, so this is not a 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 coverage is 100% with thorough descriptions for all 4 parameters, including the 'entities' order semantics and the '_apiKey' requirement. The description reinforces that the first entity is the subject and the rest are competitors, but this is already in the schema. There is no significant additional meaning added beyond the schema.

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

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

The description uses a specific verb ('Compare') and identifies a precise resource ('AI visibility across multiple entities'), then outlines the process (probe, rank, surface) and the output (ranked list with score/confidence/signal density). This clearly distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

It gives a concrete use case ('competitive AI-marketing audits') and an example query ('does Claude know about us as well as our competitors?'), making the intended scenario clear. It does not explicitly exclude alternatives or mention when not to use it, but the context is sufficient for an agent to select it appropriately.

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?

Discloses partial failure behavior, bundlephobia's first measurement can take 5-30s and may result in sources_failed. Adds external service fan-out context beyond what annotations (readOnly/idempotent) provide, with no contradiction.

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

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

The description is front-loaded with the core purpose, then logically covers usage, return fields, ecosystem limits, and failure handling. Each sentence serves a distinct function 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?

Despite no output schema, the description enumerates the summary block fields and other return elements. It also covers ecosystem scope and partial failure behavior, making it self-sufficient for 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 already documents both parameters at 100% coverage, so the description adds little. It reinforces the package is npm but does not introduce new parameter details 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?

Clearly states it's a composite 'should I add this npm package' check in one call, fanning out to deps.dev and bundlephobia. Distinguishes itself with NPM-only scope and alternative tool for other ecosystems.

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

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

Explicitly says use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies NPM ecosystem only and directs PyPI/Maven/Cargo/Go users to deps.dev:version directly.

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

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

Beyond annotations, the description discloses rich behavioral details: return format (character offsets, similarity scores), underlying algorithm (BGE-base-en embeddings, cosine over 500-char windows), and input limits with truncation behavior. This gives the agent a full understanding of expected behavior.

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

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

The description is long but every sentence earns its place: purpose, use case, algorithm, limits, and pairing with a sibling. It is front-loaded with the main action and avoids redundancy.

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

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

With no output schema, the description must explain return values, which it does (top-N passages, offsets, scores). It also covers edge cases (truncation flag) and the algorithm, making the tool fully understandable for a 3-parameter function.

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% parameter coverage with clear descriptions. The description adds practical examples (e.g., SEC 10-K body) but does not redefine parameter semantics, 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 opens with 'Semantic search INSIDE a fetched record,' clearly identifying the verb and resource. It also distinguishes itself from sibling tools by noting it pairs with ask_pipeworx_grounded, making its unique role explicit.

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

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

The description explicitly states when to use the tool ('Use when the record is too big to cram into the prompt') and provides a complementary tool (ask_pipeworx_grounded), giving the agent clear contextual guidance 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 declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the exact return content (label and description) and provides naming examples, which goes beyond structured 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, compact sentence with useful examples and no filler. It is front-loaded with the essential purpose and return fields.

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

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

For a simple one-parameter lookup tool with rich annotations, the description covers the key return fields (label, description). It could explicitly mention how to discover valid series names, but that is implied by sibling tools and the examples.

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

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

The schema fully documents the series parameter with a description and example. The description repeats the example but does not add additional parameter semantics, so it 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 returns metadata for a single series, specifically label and description, and gives concrete examples. This distinguishes it from siblings like list_series, which likely return multiple series.

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 a known series name via 'single series' and examples, but it does not explicitly state when to use this over list_series or other discovery tools. No alternatives or exclusions are mentioned.

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 context beyond annotations: requires OAuth, phone verification for SMS, 10/day SMS cap, and the always-on feed. This aligns with the annotations (readOnlyHint=false, idempotentHint=true) 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 front-loaded with purpose and return value, then prerequisites, types, and delivery channels, all in five efficient sentences. Each sentence adds necessary information 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?

The description covers many aspects but omits two subscription types (patent_grant, clinical_trial) from the schema enum and does not mention the webhook delivery channel. This gap could prevent an agent from using those features, making it incomplete for full context.

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

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

Schema coverage is 100%, but the description enriches it with concrete examples (e.g., items:["5.02"] = officer change) and clarifies type-specific parameter meanings, going beyond bare schema definitions.

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

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

The description opens with the specific action 'Create a proactive monitoring subscription to a live-data event stream,' clearly distinguishing it from siblings like list_subscriptions and unsubscribe. It also mentions the return value (subscription id), fully clarifying the tool's 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?

It gives explicit prerequisites (Pipeworx OAuth account) and states that anonymous/BYO cannot persist subscriptions, implying when not to use the tool. It also provides concrete examples of supported types and delivery channels, though it does not explicitly name alternative tools for similar actions.

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, non-destructive, and idempotent behavior. The description adds useful context about what the tool returns (category-bucketed examples with tool + argument shape) and its role as an onboarding aid, which goes beyond the structured annotations.

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

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

The description is longer than average but every part earns its place: example queries aid pattern matching, the return format is explained, and usage guidance is front-loaded. It is structured well, though slightly verbose for a simple one-parameter 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 explains what the tool returns (category-bucketed example questions with tool+argument shape) and how to call it (with or without topic). It also covers when to use it and its relationship to other tools, making it contextually complete.

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

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

Schema coverage is 100% and the schema already describes 'topic' with examples and the omit-for-full-spread behavior. The description reinforces this but adds no new semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns category-bucketed example questions with the exact tool + argument shape, and explicitly positions itself as the onboarding entry point. It distinguishes from siblings like discover_tools by naming its role as the first stop for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance and names alternatives (ask_pipeworx, entity_profile, compare_entities), satisfying the dimension fully.

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

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

The description adds significant behavioral context beyond annotations: it explains that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This clarifies the soft-delete nature and side effects, which annotations alone do not convey.

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

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

Two concise, front-loaded sentences. The first sentence states the action, and the second provides essential behavioral nuances. Every word earns its place, with no fluff or redundancy.

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

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

For a simple single-parameter tool, the description covers the core action, ownership constraints, and post-effects. Combined with annotations that specify idempotency and non-destructiveness, the tool is fully contextualized without needing an output schema.

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

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

The input schema already provides 100% coverage of the 'id' parameter, describing it as a UUID returned by subscribe. The description merely repeats 'by id' without adding further 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 states a specific verb (cancel) and resource (subscription) with a clear scope (by id). This distinguishes it from sibling tools like subscribe and list_subscriptions, 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 clearly indicates when to use the tool (to cancel a subscription by id) and includes an important usage constraint (ownership enforced). It does not explicitly name alternative tools or exclusion scenarios, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds critical behavioral context beyond annotations: the two pipeline routes, the exact verdict categories, and especially the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covers it). This is crucial for correct interpretation and goes far beyond the structured 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?

Although the description is long, it is densely informative and well-structured. It front-loads the core purpose, then covers two pipelines, return values, and critical caller warnings, all in a compact block. Every sentence earns its place; the length is justified by the tool's complexity and the need to prevent misuse of 'could_not_verify'.

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

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

With no output schema, the description carries the burden of explaining return values—it lists the verdict enum, cites the grounded/structured value with a pipeworx:// citation, and explains reasoning. It also covers edge cases (could_not_verify vs. unsupported) and the two routing paths, making it fully self-sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%; both 'claim' and 'tolerance_pct' are well-documented in the schema itself, so the description adds little parameter-level detail. The description references the percent-delta math and tolerance override but does not add new semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with natural-language trigger examples ('Is it true that…' / 'fact check' / 'verify the claim that…') and explicitly states the tool's function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself from sibling research tools by focusing on claim verification, not open-ended research or entity queries.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates two paths (structured SEC EDGAR fast path for company-financial claims vs. grounded pipeline for any other factual claim) and notes it replaces 4–6 sequential calls, signaling this is the consolidated tool for such checks.

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