Statcan

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

Discloses return structure (per-model score, confidence, signals, raw_response + combined view), free default model, and BYO key for Anthropic. No contradiction with annotations (readOnlyHint, idempotentHint, etc.). Adds significant context beyond annotations.

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

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

Single paragraph, front-loaded with main action, every sentence adds value. Succinctly covers purpose, parameters, use cases, and return format without waste.

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

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

Despite no output schema, description details return shape per model and combined view. Covers models, API key, disambiguation, and use cases. Fits complexity of probing multiple LLMs.

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

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

All 4 parameters described in schema. Description adds context: default model, BYO key, use cases. Provides meaning beyond schema, e.g., explaining _apiKey purpose and entity disambiguation via context parameter.

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

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

Clear verb 'Probe' and 'score' with specific resource (LLMs, visibility). Distinguishes from siblings like scan_competitor_ai_presence by focusing on visibility scoring. States use cases: AI-marketing audits, brand checks, competitive monitoring.

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 default model and optional _apiKey for Anthropic, guiding parameter usage. Implicitly suggests when to use via use cases, but lacks explicit when-not or alternatives compared to siblings.

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

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

Annotations (readOnly, openWorld, idempotent, non-destructive) cover safety; description adds context: routes to 5,578 tools, returns stable citation URIs, works on all tiers, and is a single fast call. No contradictions, but does not mention failure modes or rate limit edge cases; still adds value beyond annotations.

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

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

Concise despite length—every sentence provides actionable info. Front-loaded preference statement, examples, comparisons to siblings, and scope all serve purpose. No filler.

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

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

For a wide/routing tool without output schema, it thoroughly covers scope, alternatives, prerequisites, and examples. It explains when to use grounded/deep_research, and notes it covers news and live data, making it self-contained.

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 aliases with 100% description coverage. Description adds value through specific query examples (Apple revenue, SEC filings, bitcoin price), clarifying expected input style and acceptable domains.

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

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

Clearly states the tool routes questions to structured data sources and returns cites answers. Distinguishes from siblings (grounded, deep_research) and provides concrete examples, making the function unambiguous.

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

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

Explicitly instructs to prefer over web search, lists trigger phrases and domains, and defines when to step up to alternatives. Also calls it the default entry point, giving strong 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?

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds significant behavioral context: it discloses the current inactive state of candidates, that it matches ask_pipeworx exactly at present, and that it has no fallback ('Falls back to nothing — this IS a full working router'). This goes beyond the annotation safety profile and clarifies the beta nature.

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

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

The description is three sentences, each earning its place: it defines the tool as a beta version, states the current state (no active candidate), and gives usage guidance. It is front-loaded with the core purpose and free of fluff, remaining concise while covering all critical aspects.

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 moderate complexity (a router with many underlying tools) and rich annotations/schema, the description covers all essential context: what it does, how to use it, its experimental nature, current status, and relationship to the stable router. It explains the fallback behavior and response shape parity, making it complete for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage with descriptions for all six parameters (all aliases of 'question'). The description adds no parameter-specific meaning beyond referencing 'same arguments' as ask_pipeworx. With full schema coverage, baseline 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,578 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by mentioning candidate routing improvements under test, making its purpose specific and unambiguous.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives clear when-to-use guidance and implicitly points to ask_pipeworx as the stable alternative, fulfilling the need for alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses that it costs an extra LLM call, returns evidence and confidence, refuses with specific reasons when data isn't sufficient, and only uses tool results for answers.

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

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

The description is dense but well-structured: it defines the purpose, explains the process, lists the return fields and refusal reasons, and gives usage guidance. Every sentence adds value with no redundancy.

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

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

The description covers the tool's functionality, usage scenarios, cost tradeoff, and output format. It is sufficiently complete for an agent to decide when to use it and what to expect, without needing extra details.

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

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

The schema fully describes the parameter (question) with 100% coverage, including aliases. The description adds no extra meaning about the parameter itself, 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 clearly states the tool's purpose: a hallucination-resistant answer mode that selects the right tool, fetches data, and extracts answers only from the tool result. It also specifies the return format and refusal conditions.

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

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

Usage is explicitly contrasted with the sibling ask_pipeworx: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' This provides clear when-to-use versus 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?

The description goes far beyond annotations, disclosing the fan-out process, response shapes, resolver contract, parent event extraction, news fallback mechanisms (with _fallback_attempted fields), safety short-circuits (low_confidence_match, market_closed_or_inactive), and resolution-rule risk (cancellation_rule parsing). It does not contradict any annotations.

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

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

The description is long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the core purpose. While it is verbose, the detail is necessary for a complex tool, and every section provides valuable information. Could be slightly more concise, but structure compensates.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is exceptionally complete. It covers input handling, internal fan-out logic, response fields, edge cases (low confidence, closed markets, wide spreads, news fallbacks), and even resolution rules. The agent can reliably use this tool without needing additional information.

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

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

All three parameters have schema descriptions, and the tool description adds significant context: it explains the 'quick' vs 'thorough' depth values with implications for the number of sources, and clarifies the 'include_raw' parameter's effect on response size. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies the input formats (slug, URL, question text) and gives concrete use cases ("should I bet on X"). It distinguishes itself from sibling tools by focusing on single-bet research with data fan-out, which is unique among the listed siblings.

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

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

The description explicitly says "Use for..." with example questions. It also details behavior in various scenarios (low confidence, closed markets, wide spreads). However, it does not explicitly state when NOT to use it or compare to alternatives like polymarket_edges, which would be helpful for an AI agent deciding between 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 declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results, and citation URIs.

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

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

The description is a single paragraph containing all necessary information efficiently. The initial list of example queries adds helpful context but slightly reduces conciseness; overall, the structure is effective.

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 specifies return format (paired data + citation URIs). It covers edge cases (off-calendar fiscal years) and provides complete context for agent usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond schema by explaining the data pulled per type, input formats (tickers/CIKs vs. drug names), and result sorting.

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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes example queries and specific data sources per entity type, and distinguishes itself from sequential lookups.

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

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

The description explicitly recommends preferring this tool over sequential single-pack lookups for comparisons. It provides input format guidance and notes the replacement of 8–15 sequential calls, but lacks explicit when-not-to-use conditions.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) are complemented by rich behavioral details: account requirements, depth behaviors, parallel routing, findings packet structure, gap handling, contradictions scan, excerpting, citation URI conditions, and time expectations. The description adds substantial transparency beyond annotations without any 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 long but every sentence contributes critical information (account, alternatives, process, outputs, caveats). It's front-loaded with the most important caveat (account required) and usage direction. While dense, it avoids redundancy and maintains a logical flow; only slight trimming could improve conciseness.

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

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

Given the tool's complexity (orchestrating 5,578 tools, multiple depth levels, gap recovery, contradiction flags, citation handling), the description covers all essential aspects: prerequisites, operational mechanics, return packet contents, edge cases (gaps, contradictions, excerpting), timing, and explicit comparisons to siblings. No output schema exists, so this description fully compensates.

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

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

Schema already has 100% coverage, but the description goes further by explaining the depth parameter's practical implications (number of facets, hop behavior, contradiction scan) and the question parameter's suitability for broad/multi-part queries. This enriches the schema's technical definitions with actionable usage context.

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

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

The description clearly states the tool's core function: 'Grounded multi-source research across Pipeworx's 1463 STRUCTURED data sources' in one call, decomposing questions into facets and routing to parallel tools. It explicitly contrasts with siblings like ask_pipeworx, making the purpose distinct and unambiguous.

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

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

Provides explicit guidance on when to use: 'Best for broad/multi-part questions over structured data', and when not to: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also names alternatives and explains why, offering both positive and negative usage cases.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full input schemas with curated examples and are ready to call directly, which is valuable behavioral context 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 comprehensive and well-structured, with an opening statement, list of domains, and usage guidance. It is slightly verbose but each sentence adds value. Could be tightened slightly.

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 (6 parameters, simple types) and the annotations covering safety, the description explains return value (tool names, descriptions, schemas) and usage context. No output schema exists, but the description adequately clarifies what to expect. Complete enough for agent selection.

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

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

Schema description coverage is 100% and includes detailed descriptions for each parameter, including aliases. The description provides an example of the query parameter but adds minimal additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with "Find tools by describing the data or task," clearly stating the verb (find/discover) and resource (tools). It distinguishes from sibling tools (e.g., specific data retrieval tools) by being a discovery-first tool, listing numerous example domains like SEC filings, FDA drugs, etc.

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 "Call this FIRST when you have many tools available and want to see the option set (not just one answer)." This gives clear when-to-use guidance and implies this tool is for exploration, not final answer retrieval.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: fanning across multiple sources, soft-fail for patents, fallback for news, and specific return fields. 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?

Front-loaded with query examples, then clear purpose, then detailed behavior. Every sentence is informative and earns its place. No 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?

Despite no output schema, the description fully enumerates return fields (cik, company_name, filings, fundamentals, patents, news, LEI) and notes limitations (patents sunset, name restriction). 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 descriptions for both parameters. The description reinforces the meaning, especially for value (ticker vs CIK) and type (only company), and adds context about unsupported name inputs, going beyond the schema.

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

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

The description starts with concrete query examples, then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling tools like resolve_entity and chained single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and specifies when not to use it: 'names not supported (use resolve_entity first).' Provides clear context and alternatives.

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

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

Annotations already declare destructiveHint=true, so the description's mention of deletion adds minimal new behavioral insight beyond confirming the operation type.

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

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

Two concise sentences, front-loaded with the core purpose, followed by usage context. 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?

Given a simple single-parameter tool with complete schema and annotations, the description adequately covers usage and purpose but could mention irreversibility (though hinted by destructiveHint).

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 single parameter 'key' fully (100% coverage), and the description 'by key' adds no extra meaning beyond what's 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 clearly states the action ('Delete'), the resource ('memory'), and the scope ('by key'). It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

The description provides explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with related tools, but lacks explicit 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context by detailing the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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 two concise sentences with an enumerated list of use cases, front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description fully explains the output (single text blob) and the tool's behavior. With 2 parameters and complete schema coverage, the description is sufficient for effective use.

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

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

Schema description coverage is 100%, with both parameters (url, max_links) already described in the input schema. The description adds no additional semantic information beyond the schema, so 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the purpose for AI crawlers. It effectively differentiates from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on the specific output format.

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

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

The description provides explicit use cases (client site indexing, own project, competitor audit) but does not state when not to use the tool or mention alternatives. It gives clear context for when this tool is appropriate.

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

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

Annotations (readOnlyHint, destructiveHint=false, etc.) already signal safe, idempotent operation. Description adds return field details but doesn't expand beyond annotations. 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?

Two sentences, front-loaded with core purpose, includes return fields and usage guidance. No unnecessary words.

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

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

Simple tool with one optional param. Description lists return fields and provides usage context. Slight lack of details on potential pagination or list size, but adequate for 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?

Schema coverage is 100% with one optional boolean parameter fully described. Description does not add new parameter information beyond the schema, so 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?

Clearly states the verb ('List'), resource ('caller's active subscriptions'), and specifies return fields (id, type, params, etc.). Distinguished from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises when to use: 'to review what you're monitoring before adding more' or 'to find an id to cancel'. Does not mention when not to use, but provides sufficient context.

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

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

Beyond annotations (which are all false), the description discloses rich behavioral details: filing without an account returns a claim_token, passing it back later allows reading resolution status, reports are rate-limited to 5 per identifier per day, and the tool is free and doesn't count against quota. It also instructs users to describe issues in terms of Pipeworx tools rather than pasting end-user prompts. 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 slightly long but every sentence earns its place, covering purpose, usage, exclusions, claim_token flow, rate limits, and content guidance. It is front-loaded with the core purpose and then provides necessary operational details. Minor deduction because some motivational phrases ('signal directly affects roadmap') are optional but not bloated enough to be a significant issue.

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 (optional params, nested context, claim_token flow, and exclusions), the description is remarkably complete. It explains the feedback types, how to structure feedback, the claim_token return and subsequent use, rate limits, and non-quota status. Though no output schema is provided, the description sufficiently hints at what the tool returns (claim_token and resolution status).

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, so baseline is 3. The description adds value beyond the schema by explaining the claim_token workflow ('pass the pwfb_… token that filing returned, with no other arguments') and offering guidance on message content ('Be specific (which tool, what error, what data was missing). 1-2 sentences typical, 2000 chars max'). It does not systematically re-describe each parameter but contextualizes the most nuanced one.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by focusing on feedback submission rather than data retrieval or analysis.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an exclusion and alternative: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' 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 readOnly, idempotent, and non-destructive. Description adds cache behavior (5min-1h), data source (CF analytics-engine), and no-PII claim, providing useful context beyond annotations.

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

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

Two sentences plus bullet points. Front-loaded with main output. Every sentence adds value, no redundancy.

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

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

For a simple read tool with one optional param and no output schema, the description fully covers what it returns, cache behavior, use cases, and data source origin.

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 100% of parameter descriptions, so baseline is 3. Description does not add new parameter details but ties window choices to use cases (short vs long windows). No additional clarification needed.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over a recent window, specifying the resource and scope. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on aggregated usage trends from other agents.

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 three explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use cases with trends. Lacks explicit 'when not to use' but offers clear positive guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals detailed behavioral traits: monotonicity checks, partition-sum validation, semantic anchor with Jaccard threshold, placeholder filtering, fill check via CLOB depth, and trade eligibility conditions.

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 thorough but lengthy. It is well-structured with clear mode explanations and technical notes, though some detail (e.g., fill check mechanics) could be more concise without losing clarity.

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 partially explains the response structure (opportunities[], partition_check, fill check). It covers essential details for usage but leaves some output fields undefined (e.g., types of gaps). Still quite complete given 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 adds substantial meaning beyond parameter names/types. It explains event slugs with examples, topic as seed question, and the behavior when no arguments are given. This enhances parameter understanding.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending scan, event, topic) and differentiates from sibling tools like 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?

Explicit guidance on when to use each mode: '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 explains cross-event mode catches patterns single-event misses.

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. The description adds extensive behavioral details: model family logic (lognormal, GDELT, partition_overround), response structure (by_segment, diagnostics), caching (1h at KV level), and edge calculation (slippage, Kelly fractions, liquidity filters). 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 long but well-structured: summary, model details, response structure, tradeable-edge knobs, top-level fields. It front-loads the main purpose. While some technical details (specific α, gate thresholds) could be trimmed, the structure is efficient for the complexity.

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

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

Without an output schema, the description thoroughly explains response structure (by_segment, diagnostics, fed_candidates, keys per opportunity) and behavior (caching, edge calculation, filters). It covers all necessary aspects for an agent to use the tool effectively.

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

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

Schema coverage is 100% with detailed parameter descriptions (e.g., min_partition_leg_kelly explains its interaction with partition arbs). The description adds some extra context in the 'TRADEABLE-EDGE KNOBS' paragraph, but the schema already provides strong semantics, 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It names three segments (model_driven, structural_arbitrage, concentrated_longshot), distinguishing it from siblings like polymarket_arbitrage.

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 'Built for what should I bet on today' and mentions caching and diagnostics, implying usage for discovery. It does not explicitly state when not to use or name alternatives, but the context allows agents to infer appropriate use.

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

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

The description adds significant behavioral context beyond annotations: it explains the data source (daily snapshots), response structure (tracked, expired, snapshot_dates), limitations (60-day TTL, snapshot frequency based on cache misses), and how decay is computed. 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 appropriately detailed and well-structured, using a question to frame purpose and listing response fields in a clear format. It is not overly verbose given the complexity, though minor trimming could be possible.

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

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

Given that the tool has no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and relevant limits. It provides complete context for an AI 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?

The schema already provides descriptions for both parameters (100% coverage). The description adds value by clarifying defaults, bounds (days clamped 2-30), and explicit values for window ('24hr', '1wk', '1mo'), which enriches understanding beyond schema.

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

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

The description clearly states the tool's purpose: to provide edge persistence and decay telemetry from daily snapshots. It distinguishes itself by focusing on historical tracking and the lifespan of edges, contrasting with sibling tools like polymarket_edges which likely provide current snapshots.

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

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

The description explains when to use the tool (to understand edge longevity and decay) and implies its value by contrasting fresh vs. old edges. However, it does not explicitly state when not to use it or provide direct comparisons to sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond annotations: explains that it walks the ladder, returns fill details and verdict, and warns about partial basket fills converting arb into unhedged directional position. 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?

Description is well-structured with a clear opening sentence, bulleted details for each mode, and usage guidance at the end. Every sentence provides useful information. While slightly long, it is front-loaded and effectively organized.

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

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

No output schema, so description carries burden of explaining return values. It lists return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs, etc. for basket). Also covers edge cases (partial fills, forced directional risk). Minor gap: exact output structure/types not specified, but sufficient for agent understanding.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: explains how market/event determine mode, side defaults (auto for basket), interpretation of size_usd (max spend on buys, target proceeds on sells for single-market; settlement notional shares per leg for basket). Provides essential context not in schema alone.

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

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

The description clearly states the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool.

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

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

Explicitly states required parameter (market or event), provides defaults for side and size_usd, and gives concrete usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', including reasoning about theoretical overround and partial fill risks.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: safety fields (compatibility_warning, temporal_alignment, skipped_* counters), conditions for meaningful spreads (equivalent bet shapes), and the warning that most topics return warnings. 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 verbose but well-structured with clear sections (modes, response, safety fields). It front-loads the purpose and uses bullet-like formatting. Some repetition could be trimmed, but the complexity justifies the 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?

Despite lacking an output schema, the description thoroughly covers return values (leg-by-leg prices, matched spreads with pp, safety fields) and explains edge cases (compatibility_warning conditions, temporal alignment). It provides enough context for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the topic shortcuts (10 macros), the override behavior of explicit parameters, and giving examples of ticker formats. It clarifies that topic is pre-mapped and explicit parameters override the mapped side.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, using the specific verb 'spread' and resource 'two venues'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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 explains two modes (topic vs explicit) and gives guidance on when to use each. It warns that most pre-mapped topics return compatibility_warnings and are not tradeable. However, it does not explicitly exclude alternatives or provide when-not-to-use scenarios beyond the warning.

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 and non-destructive behavior. The description adds scoping details and the behavior when omitting the key (lists all), but doesn't add contradictory or missing information.

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

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

Three sentences, all essential, front-loaded with the main action. No redundant or unnecessary text.

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 retrieval tool with good annotations and schema, the description is complete enough, though it doesn't describe the return format (no output schema). It covers usage, scoping, and sibling relationships.

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 parameter fully (100% coverage). The description reinforces that omitting the key lists all keys, which adds clarity beyond the schema's required list.

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 saved values or lists all keys, with specific examples like ticker, address, and notes. It distinguishes from siblings remember and forget.

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

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

Explicitly states when to use (look up stored context), implies when not (use remember/forget for save/delete), and names alternatives. Also mentions scoping to identifier.

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

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

Description describes mark_read side effect (flags events as read) which is a write operation, contradicting annotations' readOnlyHint=true. This is a serious inconsistency.

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?

Very concise: three sentences, front-loaded with main purpose, 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?

Describes return fields (source, citation_uri, payload) which is critical since no output schema. Covers parameters and usage. Lacks error handling info but sufficient for typical use.

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

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

Schema coverage is 100%, but description adds context: example for type ('sec_8k'), explains mark_read effect, clarifies since as ISO timestamp.

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 pulls fired events from subscription feed, returns recent alerts with source, citation_uri, payload. Gives example filter and alternative HTTP endpoint.

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 'Polls work fine' and mentions alternative access via HTTP. Provides filtering guidance with examples, but doesn't explicitly contrast with sibling tools like list_subscriptions.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds fan-out behavior, fallback logic, and soft-fail details, providing significant extra transparency 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?

Description is long but well-structured with front-loaded examples and clear sections. Could be slightly more concise but each sentence adds value.

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

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

Despite no output schema, description explains return structure (changes grouped by source, total_changes count, citation URIs). Parameters fully documented and behavior clear.

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 100% parameters with descriptions. Description adds context on accepted formats, example values, and explains CIK acceptance, going beyond schema.

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

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

The description clearly states it provides a change feed for a company in a recent time window, listing multiple sources (SEC, GDELT, USPTO) and distinguishing from the sibling tool entity_profile that gives static profile.

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 scenarios and alternative tool (entity_profile). It does not explicitly state when not to use, but the context and sibling tool name suffice.

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

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

Description adds behavioral details beyond annotations: key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users, and mention of idempotency. 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?

Five sentences, front-loaded purpose, no wasted words. Could be slightly more concise but still efficient.

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

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

Given no output schema needed for a setter, description covers persistence, scoping, lifetime, and pairing with other tools. 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%, so baseline 3. Description adds value with examples for key ('subject_property') and explains scoping, slightly improving semantics.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses specific verb 'save' and resource 'data for reuse', and distinguishes from siblings like recall and forget.

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: 'when you discover something worth carrying forward'. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' Provides clear context and exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral traits: it 'cascades through several lookup endpoints internally,' gracefully degrades when GLEIF/OpenFIGI are unavailable, explicitly lists unresolved identifiers under `unresolved`, and labels each identifier with its source. This far exceeds what annotations alone provide.

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

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

The description is a single dense paragraph, which hinders scannability. It front-loads examples but then dives into nested explanations of cross-source identity spines, GLEIF, OpenFIGI, and RxNorm. While all information is relevant, it could be structured with bullet points or shorter sentences. It earns a 3 because it is not concise, though it is not excessively redundant.

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 what the tool returns, and it does so thoroughly: for company, it lists CIK, ticker, company_name, LEI, FIGI, and ownership data; for drug, RxCUI, ingredient, brand, and citation. It also covers unresolved handling and graceful degradation, making the tool's behavior understandable even without a formal 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?

Even though schema coverage is 100%, the description greatly enriches parameter meaning. For `type=company`, it explains that `value` accepts 'ticker, CIK, ISIN, or company name' and details ISIN-to-LEI mapping. For `type=drug`, it specifies returns. It also provides concrete examples ('ozempic', 'metformin', 'CH0038863350'), adding value beyond the schema's basic descriptions.

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

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

The description opens with concrete user phrasings and explicitly states that the tool 'resolve[s] a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by the directive 'Use FIRST whenever you have a name but need an ID,' making the tool's scope and entry-point role unmistakable.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use the tool and implies that if you already have an ID, you should use another tool. It also explains that the tool replaces 2-3 manual lookups, giving context on efficiency. However, it does not explicitly name alternative tools or say when not to use it beyond the ID implication, so it's not 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 declare readOnly, openWorld, idempotent, non-destructive; description adds that it performs multiple probes, ranks results, and returns score, confidence, signal density. Also clarifies API key requirement and first entity treated as subject. No contradictions.

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

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

Three sentences: purpose, method, example use case. Front-loaded, no wasted words, every sentence adds value.

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

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

Given no output schema, description adequately explains return format (ranked list with score, confidence, signal density). Covers parameter constraints (2-8 entities, API key condition). Lacks explicit mention of error handling or edge cases, but sufficient for most use cases.

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

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

Schema already has 100% coverage with clear descriptions for all 4 parameters. Description adds minimal new info beyond schema (e.g., 'first entry treated as subject'), but mostly repeats. Baseline 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check to probe each entity and ranking results. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (different comparison type).

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 usage context: competitive AI-marketing audits and example question. Implicitly suggests using ai_visibility_check for single entities, but does not explicitly state when not to use this tool or list alternatives beyond the sibling mention in the description.

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 (readOnly, idempotent), description discloses performance characteristics (5-30s bundlephobia delay), partial failure handling (sources_failed list), and graceful degradation. No contradiction with annotations.

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

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

The description is information-dense without unnecessary words, but could be structured into clearer sections (e.g., bullet points for return fields). Still efficient overall.

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

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

Despite no output schema, the description fully details the response structure (summary block, per-advisory, links, alternative versions) and edge cases (partial failures, timeout handling). Complete for a complex aggregation 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 has 100% coverage, and description adds meaningful details: scoped packages (@types/node) are accepted, version defaults to latest. This adds value beyond parameter 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 composite npm package check, explicitly listing data sources (deps.dev, bundlephobia) and the decision context ('should I add this npm package'). It distinguishes from siblings which are broader research or validation 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?

Provides explicit use cases ('is X safe / popular / small') and warns about ecosystem limitations ('NPM ecosystem only in v1'). Directly guides agent when to use and when to avoid, referencing alternative tools for other ecosystems.

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

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

Adds rich behavioral details beyond annotations: embedding model, window size, character cap (200K), truncation behavior. Annotations already indicate safe/idempotent read, and description reinforces with specific implementation limits.

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

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

Front-loaded with key purpose. Every sentence adds value. Slightly verbose but no wasted words. Structure is logical: purpose, usage, technical details.

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

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

Covers all key aspects: purpose, usage scenario, pairing with sibling, implementation details (embeddings, windows, truncation), return value description (passages with offsets and scores). No gaps given 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%, baseline 3. Description adds examples for query, clarifies text as 'document text', provides limit range and default (1-20, default 5). Adds meaningful context beyond schema.

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

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

Clearly states the verb (semantic search), resource (inside a fetched record), and scope. Distinguishes from sibling `ask_pipeworx_grounded` by describing their pairing.

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: 'when the record is too big to cram into the prompt'. Mentions pairing with `ask_pipeworx_grounded`. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and side effects. The description adds minimal behavioral context beyond the annotation, so burden is shifted to annotations.

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

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

The description is concise: two sentences with no wasted words. The purpose is front-loaded and immediately understandable.

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 with one optional parameter and an output schema present. The description adequately covers purpose and usage. Could potentially mention return type but assumed from 'list'.

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

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

Schema coverage is 100%, and the description does not add additional meaning beyond what the schema's parameter description provides ('YYYY-MM-DD (default today)'). 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 action (list), the resource (StatCan series that changed), and the context (on a given date). It distinguishes itself from sibling tools like statcan_series by specifying 'changed' series for new releases.

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 a use case: 'detect updated cubes for scheduled refreshes.' While it doesn't provide when-not-to-use or alternatives, the context is clear for a simple listing tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral context by stating it returns a URL and does not fetch the file, which is consistent and provides useful additional detail.

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

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

The description is a single, well-structured sentence with no redundant information. Every word serves a purpose.

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

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

Given the simple nature of the tool (returning a URL), and the presence of a likely output schema, the description is sufficiently complete. It could mention error handling or conditions, but not necessary for basic operation.

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 slight value by mentioning 'full cube' implying the URL is for the entire cube, but does not elaborate on parameter specifics beyond what the schema already provides.

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

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

The description clearly states the verb 'Return' and the resource 'StatCan-hosted URL for a full cube as a CSV download'. It explicitly distinguishes from likely siblings that fetch data by stating 'doesn't fetch the file — hands back a direct URL'.

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

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

The description implies when to use it (when you need the URL without downloading), but does not explicitly mention when not to use it or compare to alternatives like statcan_cube_data.

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. Description adds coordinate format context but no additional behavioral traits beyond what annotations provide. 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?

Two concise sentences. First sentence states purpose, second explains coordinate usage. No unnecessary words. Front-loaded and efficient.

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

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

Given annotations, output schema, and schema coverage, the description is complete. No gaps; explains coordinate and references metadata tool. Return values covered by output schema.

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

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

Schema description coverage is 100%, so baseline is 3. Description repeats coordinate format and mentions trailing zeros, mirroring schema. No new semantics beyond schema for any parameter.

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

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

Clearly states it retrieves the latest N observations for a specific series within a StatCan cube. Explains the coordinate parameter and references statcan_cube_metadata for dimension mapping, distinguishing it from siblings like statcan_series and statcan_cube_metadata.

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?

Implicitly suggests use when coordinate and product_id are known, but lacks explicit guidance on when to prefer this tool over alternatives or when not to use it. No when-to-use or when-not-to-use statements.

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. The description adds context about the return content (dimensions, member trees, etc.), which is useful but not essential given the annotations and output 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 two concise sentences. The first sentence specifies the resource and what it provides, the second gives direct usage guidance. No superfluous content; every sentence earns its place.

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

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

Given the single parameter, full schema coverage, comprehensive annotations, and presence of an output schema detailing return values, the description sufficiently covers the tool's purpose and usage context. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and the parameter description in the schema is clear. The tool description adds a usage hint (constructing coordinate strings) but does not provide additional parameter semantics beyond what the schema already offers, meeting 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 clearly states the tool retrieves full metadata for a StatCan cube, listing specific details like dimensions and geography. It also differentiates itself from the sibling statcan_cube_data by explaining its use in constructing coordinate strings for that tool.

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

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

The description explicitly advises to use this tool before statcan_cube_data to construct coordinate strings. While it doesn't list when not to use it, the context of the sibling tools implies its primary role is preparatory, providing clear 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, openWorld, idempotent, and non-destructive. The description adds return behavior ('Returns the latest value plus recent history') and notes quarterly population estimates, providing useful context beyond annotations without contradiction.

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

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

Three concise sentences front-load the tool's purpose, explicitly call out preferred use cases, and mention the pointer to statcan_series. No filler; every sentence adds actionable information.

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

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

Despite lacking an output schema, the description states the return format (latest value plus recent history) and covers the main parameters and their constraints. For a simple headline-indicator tool, this is sufficient and complete.

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

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

Input schema covers all parameters with 100% description coverage, so baseline is 3. The description adds value by explaining friendly name aliases ('cpi (=inflation)'), the conditional geography parameter for population, and the optional 'recent' observations, going beyond the schema's basic 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 identifies the tool as retrieving headline Canadian indicators from StatCan, listing specific indicators (CPI, unemployment, GDP, population) and geographies (Canada/provinces/territories). It also distinguishes from sibling tools by explicitly naming statcan_series for other uses.

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 for specific queries like 'Canada inflation', and use statcan_series for anything else. Also clarifies friendly name aliases and that geography is optional/for population only, giving clear when-to-use context.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds value by explaining the response contains a lean set of fields and is large (~3,000 cubes), which informs agent 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?

Two sentences, front-loaded with purpose. No wasted words; includes essential context (fields, size, downstream use).

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 zero-parameter tool with rich annotations and output schema, the description fully explains what it returns, its size, and how to use the output. No missing critical information.

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

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

No parameters; description correctly indicates no input needed. Schema coverage is 100% (no params to describe), so baseline 4 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?

Clearly states it lists all StatCan cubes with specific fields (productId, title, CANSIM id, etc.). Distinguishes from siblings by directing to use productId with statcan_cube_metadata/statcan_cube_data.

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

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

Explicitly tells to use productId from this tool with other tools, and notes the large response size requiring client-side filtering. Implicitly suggests when not to use (when needing full metadata/data).

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

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

Annotations already mark the tool as read-only and idempotent. The description adds value by stating it returns recent observations and series title, and notes where to find vector ids. 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?

Two sentences, front-loaded with purpose, includes an example. No unnecessary words.

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

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

No output schema exists, and the description only says 'returns recent observations + series title' without detailing the format. Misses potential error handling or data structure.

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 includes parameter descriptions. The description adds a concrete example and usage note, but does not significantly deepen 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 states the tool fetches a Statistics Canada series by vector id, using 'Fetch' and giving an example. However, it does not explicitly distinguish this tool from sibling StatCan tools.

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

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

The description provides context on when to use (escape hatch, find vector ids) but does not guide when to avoid or which sibling to prefer instead.

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: requirements for OAuth account, that anonymous/BYO cannot persist, detailed types with examples, delivery channels with limitations (10/day SMS cap, email format, webhook auto-disabling after 10 failures). Annotations indicate readOnlyHint=false (creation), openWorldHint=true (dynamic params), idempotentHint=true (retries safe), destructiveHint=false. 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 main purpose and then details. It is somewhat lengthy due to the examples and delivery details, but every sentence adds value and no redundancy is present.

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

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

Given the complexity (3 parameters, nested objects, multiple types), the description covers all necessary aspects: purpose, requirements, examples, delivery channels with constraints, and return value (new subscription id). No output schema exists, but the return is stated.

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

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

Schema coverage is 100%, but the description adds concrete examples for each enum type (e.g., sec_8k items codes, polymarket_edge topic, fred series_id) and explains delivery object fields in detail (SMS must match verified phone, webhook signing and auto-disable). This adds value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by specifying the action (create) and the resource (subscription).

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 on when to use the tool (to subscribe to alerts) and includes prerequisites (requires a Pipeworx OAuth account). It does not explicitly state when not to use or compare with alternatives, but the sibling list makes it clear this is the creation tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context: the tool returns example questions drawn from the live catalog and that it serves as an onboarding entry point. No contradictions; the description enhances transparency 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 moderately long but well-structured, front-loading the purpose and usage scenarios. It uses parenthetical lists and a clear call-to-action. Although it could be slightly shorter, every sentence adds useful information.

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

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

Given no output schema, the description adequately explains what the tool returns (category-bucketed example questions with tool+argument shapes). It also covers the optional topic parameter. For a discovery tool, this is sufficient context.

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

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

Schema coverage is 100% with one parameter (`topic`). The description reinforces the parameter's purpose, lists possible values, and explains how omitting it gives a cross-category spread. This adds value by clarifying usage context beyond the schema's bare description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions as an onboarding entry point for a new agent. It distinguishes itself from siblings by explicitly positioning it as the first tool to use when the agent doesn't know 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?

The description explicitly tells the agent to use this tool first when unsure about Pipeworx's capabilities. It also explains that it can be called with no arguments for a full spread or with a specific topic. However, it does not explicitly exclude alternatives or mention when not to use it.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and that historical events remain available via recent_alerts. This is valuable for an agent.

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 with no wasted words. The purpose is front-loaded, and each sentence adds essential information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, ownership, behavior, and side effects. It references the related `recent_alerts` tool for context.

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

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

The single parameter 'id' is fully described in the schema (100% coverage). The description only mentions 'by id', adding no significant 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 uses a clear verb 'Cancel' and specifies the resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion). It provides clear context but could explicitly mention when not to use this tool (e.g., for permanent deletion).

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

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

The description goes beyond the annotations by disclosing critical behavioral details: the meaning of 'could_not_verify' (check did not happen, NOT evidence) and 'unsupported' (no source found), plus the pipeline behavior ('routed to the right live source, answered with verbatim evidence, then judged'). This is essential for correct interpretation of results and far exceeds the minimal readOnly/idempotent hints.

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

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

The description is well-structured, starting with example user phrases to aid recognition, then the purpose, then behavioral details, and a closing note about replacing multiple calls. It is a bit long, but every section adds necessary information; the opening phrase list is slightly redundant but helpful for triggering correct invocation.

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

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

With no output schema, the description fully explains the return value: verdict types, actual value with citation, and reasoning. It also clarifies the semantics of two verdicts (could_not_verify, unsupported) and warns about not misusing them. Given the tool's complexity (varying claim types, routing, edge cases), the description is remarkably complete and self-sufficient.

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

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

The schema already covers both parameters fully (claim with examples, tolerance_pct with range and default). The description adds context like 'exact percent-delta math' but does not provide additional parameter-specific semantics that would raise the score above the baseline for high schema coverage. It is a standard case where 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 ('natural-language claim verification against authoritative sources') with a specific verb ('validate') and resource ('factual claims'). It also distinguishes itself from siblings by noting it 'Replaces 4–6 sequential calls' and describing its dual-path routing for financial vs. other claims, making its scope clear.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', giving a clear context. However, it does not mention when NOT to use this tool versus alternatives (e.g., deep research), so it lacks exclusions. It also explains the two distinct paths depending on claim type, which is additional guidance.

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