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?

With readOnly/openWorld/idempotent annotations already covering safety, the description adds meaningful behavioral detail: it routes to sub-tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It does not describe failure or no-result behavior, but this is minor given the annotation coverage.

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

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

The description is long but front-loaded with the key preference, and every sentence adds needed guidance: source categories, routing behavior, trigger phrases, examples, and the deep_research alternative. There is no filler or repetition.

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

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

For a routing tool with no output schema, it covers the input style, return behavior, when to prefer it, and the main alternative. It could mention what happens if no source matches, but the provided context is enough to select and invoke the tool correctly in most cases.

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

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

Schema coverage is 100% and the schema already defines 'question' plus aliases. The description adds illustrative examples but no new parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens by saying to prefer this over web search and clearly states the tool routes a question to one of 5,798 tools across verified sources, fills arguments, and returns a structured answer with citations. This is a specific verb+resource and it distinguishes from deep_research and general web search.

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 'PREFER OVER WEB SEARCH', gives use-whenever conditions with trigger phrases like 'look up' and 'get the latest', and provides a counter-usage: 'for broad, open-ended research requiring synthesis, use deep_research instead.' Examples anchor appropriate calls.

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, idempotent, open-world, and non-destructive. The description adds meaningful behavioral context beyond that: it is an experimental edge with candidate routing improvements enabled only when under test, currently has no active candidate so it behaves identically to ask_pipeworx, and explicitly clarifies it is a full working router rather than a fallback stub. This is far beyond the annotation baseline.

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

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

The description is a single compact paragraph with no wasted sentences; every clause contributes beta status, current state, usage, or clarification. It front-loads the core identity and sibling relationship. The last sentence about 'falls back to nothing' is a slight extra but earns its place by preventing a misunderstanding.

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

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

For a complex routing tool with no output schema, the description supplies essential context: identical tool set, arguments, and response shape as ask_pipeworx, current experimental state, and a usage directive pointing to ask_pipeworx behavior. It doesn't spell out response details, but says they match ask_pipeworx, which is sufficient for agents that know the sibling.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question', so the schema carries the parameter documentation burden. The description only says 'same arguments' and doesn't add any meaning about the parameters themselves, so baseline 3 applies.

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

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

The description opens by identifying the tool as the beta version of ask_pipeworx, then precisely scopes it as an identical universal router with the same 5,798 tools, arguments, and response shape. It explicitly contrasts the beta with the stable ask_pipeworx, making the purpose and sibling differentiation 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 gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no candidate active, matches ask_pipeworx exactly) to help the agent decide when to invoke it. It doesn't explicitly name exclusion cases or stable alternatives beyond ask_pipeworx, so a 4 rather than 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context beyond that: the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the full refusal contract with enumerated refusal_reason values, and the grounding guarantee that answers are extracted 'using ONLY what the tool result contains.' No contradiction with annotations — the tool is read-only in effect despite making internal LLM calls.

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 the key differentiator ('Hallucination-resistant answer mode') and well-structured: purpose → mechanism → success shape → refusal shape → usage policy → cost tradeoff. At ~125 words it is long, but almost every sentence is load-bearing given there is no output schema to carry the return-format documentation. The example-domain list and refusal_reason enumeration add slight density but earn their place.

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

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

For a complex tool with no output schema, the description covers the essentials: routing behavior, success and refusal return shapes, the evidence/verbatim-quote guarantee, and the cost tradeoff vs the sibling. The main gap is the absence of post-refusal recovery guidance — an agent receiving refusal_reason:'not_in_source' or 'data_truncated' is not told whether to rephrase, retry, or fall back to ask_pipeworx. Confidence semantics are also left undefined, but these are minor against the strong baseline.

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

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

Schema coverage is 100% and the schema already documents the single meaningful parameter (question) plus all five aliases thoroughly. The description's mention of 'fills arguments' describes internal routing behavior, not param semantics, and adds nothing about how to phrase inputs. Baseline 3 is appropriate since the schema carries the full burden.

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

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

The description opens with a specific mode and purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the mechanism (routes across 5,798 tools, extracts answers ONLY from tool results) and explicitly differentiates from the sibling ask_pipeworx by naming the same routing plus the grounding guarantee. An agent can immediately tell what this tool is and what makes it distinct.

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

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

Provides explicit when-to-use criteria ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete example domains (financial verdicts, legal claims, medical lookups, public statements). Also gives an explicit when-not-to-use rule with the named alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is model 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?

The description goes well beyond the annotations by disclosing account/plan requirements, parallel decomposition behavior, gap reporting without invented answers, citation fetchability guarantees, semantic excerpting, contradiction scans, and expected latency. There is no contradiction with the readOnly/idempotent/openWorld annotations.

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

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

The description is dense and every sentence adds substantive caveats or behavior; however, it is a long paragraph-style wall of text. It front-loads the account requirement and fallback routing, which helps, but a more structured layout would improve scannability.

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

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

Given there is no output schema, the description carries the full burden of explaining return values, and it does: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps, contradictions, and hop fields. It also covers auth, plan gating, latency, and alternatives, making the tool locally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that 'thorough' requires a paid plan, describing expected latency by depth, and clarifying the hop and contradiction behavior for standard/thorough. This pushes it above baseline.

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

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

The description clearly states a specific verb and resource: grounded multi-source research over Pipeworx's structured data sources in one call. It explicitly distinguishes itself from open-web search and from siblings like ask_pipeworx, so an agent can select it correctly.

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 routing guidance: use ask_pipeworx when not signed in, and use ask_pipeworx for a single lookup. It also states the best use case — broad/multi-part questions over structured data — making the when-to-use decision unambiguous.

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 mark the operation read-only, idempotent, and non-destructive, so the description correctly does not reassert them. It adds substantial behavioral context beyond those hints: fan-out to multiple registries, empty sections are real 'no data' rather than bugs, sources_used/sources_failed, and resolved:false with a notes line for private companies.

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

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

The description is front-loaded with purpose and examples, but the body is one dense, run-on paragraph with many semicolon-separated source details and parentheticals. All information is relevant for the tool's complexity, but the lack of paragraph/section structure and the long clauses make it harder to scan than is ideal.

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

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

There is no output schema, so the description carries the burden of explaining return behavior; it does so by enumerating returned sections (cik, recent_filings, fundamentals, patents, etc.) and handling of failures like empty sections, private companies, and name resolution. The tool's complexity is fully covered for selection and invocation purposes.

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

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

Schema description coverage is 100%: both `type` and `value` are already documented in the input schema, so the description is not required to explain them. It adds examples and repeats the interchangeability of 'company' and 'ticker' that the schema already states, providing no material semantic increment over the structured fields.

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

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

The description opens with concrete user phrases ('Tell me about X', 'brief me on Tesla') and a specific verb-resource pair: full cross-source profile of a US public company in one parallel call. It distinguishes from single-pack SEC/XBRL/news lookups and lists specific output domains, so an agent can identify it as the holistic profile tool rather than a point lookup.

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

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

It contains an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies accepted input shapes and the behavior for private companies, which tells the agent when the tool is appropriate and what to expect when it isn't.

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?

Annotations already declare readOnly/openWorld/idempotent hints, and the description adds extensive behavioral detail: it discloses that spread_pp is gross and not net tradeable due to Kalshi fees, that compatibility flags can be non-empty even when pairs are returned, that unclassified legs are never paired, and the semantics of temporal_alignment null. This is far beyond what annotations provide and contains 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 every sentence earns its place: code meanings, fee disclosures, skipped-leg counters, and null-value semantics are all unique, necessary information. The use of caps-labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes structures the content for quick parsing despite its length.

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

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

There is no output schema, so the description carries the full burden of explaining the response. It does so thoroughly: leg-by-leg prices, top_spreads_pp, safety fields, compatibility codes, temporal alignment semantics, fees_note, skipped counters, and the warning about pre-mapped topics. Nothing an agent needs to interpret results is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds significant relational meaning: topic auto-fetches matching events on both venues, explicit ticker/slug override the mapped sides, and both modes run the identical token-overlap matcher. This clarifies how the three parameters interact and when to use each, going beyond the schema's individual parameter descriptions.

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

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

The first sentence states the exact function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This is a specific verb+resource that clearly identifies what the tool does and differentiates it from siblings like polymarket_arbitrage or bet_research. The rest of the description reinforces this focus on cross-venue comparison.

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

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

The description gives detailed when-to-use context by defining TWO MODES: topic shortcuts versus explicit event identifiers, and explains that both modes run the same matcher. It also warns that most pre-mapped topics return compatibility_warning and that 'pre-mapped ≠ tradeable,' which guides expectations. However, it does not explicitly name sibling alternatives or state when NOT to use this tool.

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

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

Annotations already 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 annotations (readOnlyHint, idempotentHint), the description discloses several behaviors: graceful degradation of LEI/FIGI enrichment, internal cascading of multiple lookups, assertion of nothing when ambiguous (returns `figi_candidates`), and explicit listing of unresolved identifiers under `unresolved`. These are non-obvious traits the agent needs to trust the tool's output.

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 and dense, but every detail earns its place given the tool's complexity. It is structured logically (purpose, types, each type's specifics, degradation), yet it could be tightened—the parenthetical about non-equity instruments is verbose. Overall, highly informative with minor 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 the absence of an output schema, the description covers return behaviors comprehensively: it mentions `figi_candidates`, `unresolved`, source labeling, and the drug-specific return fields (RxCUI, ingredient, brand, citation). It also addresses failure modes (LEI/FIGI unavailability) and edge cases (non-US issuers), leaving little the agent must guess.

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

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

Even though schema coverage is 100%, the description adds substantial meaning beyond it. For `value`, it warns against passing full noun phrases for bonds, explains the exact issuer formatting, and gives examples for both types. It also clarifies the `type` enum's implications, making the parameters far more usable.

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

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

The description states a precise purpose: resolving user-spoken names to canonical identifiers (ticker, CIK, LEI, RxCUI, etc.). It gives concrete examples and names the two supported types (company, drug), distinguishing itself as a name-to-ID utility for other tools. It is clear about the resource and the action.

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 'Use FIRST whenever you have a name but need an ID', providing strong positional guidance. It also details input constraints (pass entity name only, never the full noun phrase) and mentions it replaces multiple manual lookups, clarifying when to invoke it. It does not name alternatives, but the context and 'use first' directive 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?

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?

Adds the negative behavior 'Does NOT return vector IDs' beyond the annotations, preventing a common mistaken use. Annotations already establish read-only, idempotent, open-world safety profile, so the description only needs to add behavioral specifics.

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, each with a distinct purpose: what it returns, how to use it, and what it doesn't return with a pointer to the sibling. 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 single-parameter read-only metadata tool with an output schema present, the description covers purpose, usage, and key exclusions. Nothing an agent needs to select and call it correctly is missing.

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

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

The schema already documents product_id fully with type, description and example (100% coverage). The description adds no additional parameter-level meaning, 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?

States a specific verb (returns) and resource (StatCan cube metadata) with enumerated contents (dimensions, member trees, frequency, geography, last release). Explicitly distinguishes itself from statcan_cube_vectors by stating what it does not return, making it easy to differentiate.

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?

Gives explicit use case: construct a coordinate string for statcan_cube_data. Names the alternative statcan_cube_vectors for when vector IDs are needed, providing a clear when-to-use/when-not-to-use distinction.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context beyond that: it discloses that unfiltered dimensions include ALL members, can return thousands of rows, and describes the exact row shape (vector_id, coordinate, member labels). This gives the agent realistic expectations about scale and output.

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

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

The description is compact and every sentence earns its place: purpose, output shape, filtering risk, and next-step workflow. It is front-loaded with the primary purpose and structured so an agent can quickly decide whether to invoke it.

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

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

Even without an output schema, the description explains what rows are returned, warns about large result sets, mentions pagination/filtering, and connects the tool to statcan_series. This fully covers an agent's need to select and invoke the tool correctly within the StatCan workflow.

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

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

Schema description coverage is 100%, so the input schema already explains product_id forms, filters, page, and limit. The description reinforces filtering behavior and warns about unfiltered dimensions, but it does not add materially new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Enumerate the vector IDs inside a StatCan cube (table)'. It also explicitly positions the tool as the 'missing link' between a table number/name and statcan_series, which distinguishes it from sibling tools like statcan_series and 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?

The description gives explicit usage context: 'Every StatCan question starts with a table, but nothing else in this pack lists a table's vectors.' It also provides a clear workflow by instructing the agent to pass a returned vector_id to statcan_series for actual data, making the when-to-use and next-step guidance unambiguous.

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.