Data Montreal

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds context: the default model is free, Anthropic probes cost via BYO key, and returns per-model details. No contradiction with annotations. Some behavioral details (e.g., rate limits, concurrency) are missing, but the description is sufficient given the annotations.

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

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

The description is two sentences, each earning its place. The first sentence states the core function, the second adds details on default model, API key usage, and return structure. No fluff, front-loaded, and highly 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 the tool's complexity (4 parameters, no output schema), the description is complete. It covers inputs, output format (per-model fields plus combined view), and use cases. It does not need to explain return values further since it specifies {score, confidence, signals, raw_response}.

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

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

All 4 parameters are described in the schema (100% coverage). The description adds meaning: it clarifies the default model for 'models', explains that '_apiKey' is only needed for Anthropic, and notes that 'context' helps disambiguate. This goes beyond the schema's bare descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the verb 'probe', the resource 'LLMs', and the output 'score', effectively distinguishing from siblings like compare_entities or entity_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 explicitly mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default model and when to provide an API key. However, it lacks explicit guidance on when NOT to use this tool or direct comparisons to siblings, leaving some ambiguity.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds behavioral details: it routes to a large tool registry, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. No contradiction with annotations.

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

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

The description is long but well-structured: preference statement, mechanism, trigger phrases, examples, default entry-point note, and escalation guidance. Minor redundancy exists between 'prefer over web search' and 'even if web search could also answer it,' but overall it is appropriately dense and front-loaded.

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

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

For a broad open-world tool with no output schema, the description fully covers what queries to send, what kind of answer to expect, and when to use alternatives. It is sufficient for an agent to invoke the tool correctly across a wide range of factual questions.

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

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

The input schema already documents all parameters, including the required 'question' and five aliases, so the schema carries the semantic load. The description adds useful natural-language query examples but no additional parameter constraints, formats, or edge-case behavior.

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

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

The description clearly defines ask_pipeworx as a natural-language router: it routes questions to one of 5,724 tools across 1,497 sources, fills arguments, and returns a structured answer with pipeworx:// citations. It also explicitly distinguishes itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

It gives explicit when-to-use guidance with trigger phrases and example queries, states this is the default entry point, and tells the agent when to escalate to ask_pipeworx_grounded or deep_research. This is unusually complete routing 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 well beyond the annotations: it explains that candidate routing improvements may be live, that no candidate is currently active, that behavior currently matches ask_pipeworx exactly, and that results feed merge decisions. It also explicitly warns it is the experimental edge and that there is no fallback. This is exceptionally transparent about mutable behavior and current state.

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

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

The description is dense but efficient: it front-loads the identity and scope, then explains current status, usage, and the absence of fallback in four purposeful sentences. No sentence is wasted, and the key caveat about experimental behavior is prominent.

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

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

Given the tool is a universal router with one required natural-language argument and no output schema, the description covers the important operational details: identical behavior to ask_pipeworx, same response shape, possible live routing changes, and no fallback. It is complete enough for selection and invocation, though the actual response format is only described relationally via ask_pipeworx.

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

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

Schema description coverage is 100%, with all six parameters fully documented as aliases for the natural-language question. The description adds no parameter-specific detail, but the schema already carries the full burden. 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 states the tool is a universal router identical to ask_pipeworx, with the same 5,724 tools, arguments, and response shape. This clearly identifies what it does and distinguishes it from the stable router by its beta/experimental status. It relies somewhat on the sibling ask_pipeworx for full framing, but is not a tautology.

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 to use it exactly like ask_pipeworx when the goal is the newest routing, and notes that results are compared against the stable router. It also clarifies that it is a full working router rather than a stub or fallback. It provides a clear use condition, though it does not enumerate exclusions or alternative grounded-mode routing.

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 this read-only and idempotent, but the description adds substantial behavioral context: answers are extracted only from tool results, success returns evidence and confidence, and failures produce explicit refusal_reason values. It also discloses the extra LLM call cost, all of which goes well beyond the annotation hints.

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

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

The description is dense but every sentence carries new information: groundedness, routing reuse, return shape, refusal modes, use cases, and cost tradeoff. The most decision-relevant facts appear first, and the sibling comparison is placed where it matters most, near the end.

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 one required parameter and no output schema, the description fully covers return values, refusal behavior, when to invoke it, and when to avoid it. Nothing an agent needs to decide whether to call this tool and interpret its result 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 the single required 'question' parameter at 100% coverage, including all five aliases and the natural-language expectation. The description does not add parameter-level details beyond saying the tool 'fills arguments' during routing, so with this high schema coverage the baseline of 3 is appropriate.

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

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

The description opens with a precise verb and resource: a 'hallucination-resistant answer mode for high-stakes reads' that routes through the same machinery as ask_pipeworx and extracts answers only from tool results. It clearly differentiates itself from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusals, so an agent can distinguish them without inspecting schemas.

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 when to use this tool ('whenever an answer will be quoted, cited, or acted on... financial verdicts, legal claims, medical lookups, public statements') and when not to ('prefer ask_pipeworx for casual lookups'). The cost tradeoff ('one extra LLM call') and routing relationship to ask_pipeworx give an agent clear selection criteria.

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, destructiveHint=false, and idempotentHint=true. The description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, safety (low confidence, closed markets), liquidity warnings, cancellation rule parsing, and blocking paths. 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 very long and detailed, covering many edge cases and technical details. While well-structured with sections, it could be more concise. The front-loading is good, but overall verbosity reduces conciseness.

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

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

Given the tool's complexity (multiple data sources, classifiers, error handling), the description is remarkably complete. It covers inputs, outputs, performance trade-offs, safety mechanisms, and resolution rules. Since no output schema exists, the description fully compensates.

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

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

All three parameters are described in the schema (100% coverage). The description adds value by explaining the meaning of 'market' input formats, depth options (quick vs thorough, default), and include_raw (semantic summary vs full payload). This goes 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 states it researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from sibling tools like polymarket_edges by focusing on comprehensive research rather than just edge detection.

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 use cases are given ('should I bet on X', etc.), and examples of different bet types and fan-outs are provided. However, it does not explicitly list when not to use or contrast with sibling tools, though the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are sorted by primary metric and includes citation URIs, providing extra behavioral context without contradiction.

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

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

The description is a single dense paragraph that front-loads key triggers and purpose. Every sentence adds value, though it could be slightly more structured. No fluff.

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

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

For a comparative tool with no output schema, the description covers what data is returned for each type, sorting, and citation URIs. It also mentions parallel efficiency. Some details on error handling or edge cases could improve, but it is mostly complete.

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

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

Schema coverage is 100% and includes enums and descriptions. The description adds meaning by explaining what data is pulled for each type (10-K for companies, FAERS for drugs) and that results sort by primary metric, going beyond the schema.

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

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

The description starts with natural language triggers and clearly states it provides side-by-side comparison of 2–5 companies or drugs. It specifies verb 'compare' and resource 'entities', and distinguishes from siblings like entity_profile and deep_research.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides when-to-use guidance and examples of queries that map to this tool, making it clear when to use vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior; the description adds substantial behavioral context beyond those: account/paywall requirements, latency expectations ('Expect 15-60s... up to ~90s'), that gaps[] are never invented, that citations are always fetchable, and that large records are semantically excerpted. This is rich behavioral disclosure consistent with annotations.

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

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

The description is long and dense, but almost every sentence adds unique value: account gating, alternatives, data-source scope, return packet, depth semantics, limitations, citations, excerpting, latency. It front-loads the most critical operational constraint (account required) and the primary alternative. Minor deduction for the single run-on paragraph, which could be better structured with breaks or bullets.

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 must explain return values—and it does comprehensively: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[]' and 'contradictions[]' for standard/thorough. It also covers prerequisites, latency, limitations on current-news topics, and citation resolvability. Nothing needed to invoke the tool 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?

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds meaningful nuance by explaining what depth values do behaviorally—'standard' re-angles unanswered facets and 'thorough' chases leads—and by clarifying that the question can be broad/multi-part because decomposition is the point. This goes beyond the schema without duplicating all of it.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call.' It clearly differentiates from siblings by emphasizing 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups. An agent can immediately tell what the tool does and how it differs from nearby 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?

Usage guidance is explicit and thorough: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains when deep_research is best ('broad/multi-part questions over structured data') and when depth levels should be used. This fully answers when-to-use and when-not-to-use.

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

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

Annotations already indicate safe read-only behavior. The description adds valuable context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly,' which goes beyond the annotation statements.

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 consists of just two well-crafted sentences. The first sentence front-loads the purpose and examples; the second explains the return format and usage context. Every sentence adds value without redundancy.

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

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

Given the tool's low complexity (no output schema, simple input), the description fully covers what an agent needs: purpose, when to use, return format, and parameter behavior. Nothing essential 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 the baseline is 3. The description adds semantic value by listing multiple example queries (e.g., 'analyze housing market trends') and clarifying that multiple parameter names (task, q, search, description) are aliases for query, which is not fully captured in the schema descriptions.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many example domains, making the tool's purpose explicit and distinct from sibling tools that target specific data sources or tasks.

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 instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear guidance on when to use the tool versus alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. Description adds context: fans out across multiple sources, returns specific fields, mentions patents soft-fail and fallback chains. No contradictions. Could mention minor behavioral details like rate limits, but overall adds value.

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 that front-loads with example queries. It is dense but every sentence adds value. Could be slightly more structured (e.g., bullet points for returned fields) but remains 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?

With no output schema, the description thoroughly explains what is returned: specific fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also notes limitations (patents soft-fail, no names support). This is complete context for an agent to understand tool behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reiterates and expands: clarifies type is only "company", explains value expects ticker or zero-padded CIK, and explicitly excludes names. This adds meaningful context beyond 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 uses specific verbs like "return a full cross-source profile" and gives concrete examples ("Tell me about X", "brief me on Tesla"). It clearly distinguishes from siblings by mentioning "resolve_entity" for name resolution and implying this is a holistic view vs chaining other tools.

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

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

Explicitly states to prefer this tool over chaining single-pack lookups for holistic views. Provides precise input guidance: ticker or zero-padded CIK, not names, directing users to resolve_entity if needed. This makes selection and invocation 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 indicate destructive and idempotent. Description adds context about deleting stale or sensitive data, and clarifies it operates on previous memories. No contradiction with annotations.

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

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

Two concise sentences with no wasted words. Front-loaded with the action and resource, followed by usage guidelines.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose and usage context. Sufficient for correct invocation.

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

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

Schema coverage is 100% with description for 'key' parameter. Description does not add extra semantic meaning beyond the schema, meeting minimal 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?

Description states 'Delete a previously stored memory by key', using a clear verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' which are for storing and retrieving, respectively.

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 when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', providing context for alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior, all consistent with the description. The description adds behavioral details (fetches page, extracts title/description/key links) that go beyond annotations.

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

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

The description is concise (two sentences plus bullet points) and front-loaded with the key 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?

For a simple tool with two parameters and no output schema, the description covers purpose, usage, output format, and examples. Minor gaps (error handling) are acceptable given the tool's simplicity.

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

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

Schema coverage is 100% and describes both parameters adequately. The description does not add additional meaning beyond the schema, so it meets the baseline for a well-covered 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 verb (Generate), resource (llms.txt file), and purpose (for AI crawlers to index the site). It distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than 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 provides specific use cases (client indexing, own project, competitor auditing) but does not explicitly state when not to use the tool or mention alternatives. Still, the guidance is clear and helpful.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that it returns specific fields and defaults to active subscriptions, but no further behavioral disclosure needed 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 concise sentences: first defines purpose and output, second provides usage guidance. 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?

Tool is simple with one parameter and no output schema. Description covers return fields and typical use cases, making it complete enough for an AI agent.

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

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

Schema coverage is 100% for the single optional boolean parameter. Description does not elaborate on include_inactive beyond the schema, but the schema already suffices.

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

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

Clearly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, etc.). Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says when to use: 'before adding more' subscriptions or to 'find an id to cancel'. Does not mention 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by specifying the return format (title and resource ids) and the source (CKAN). It does not mention rate limits or pagination, but the safety profile is covered by 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 well-structured sentences. First sentence states the core action and source, second sentence describes the return value and usage hint. No filler or redundancy.

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

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

Given the low parameter count, complete schema coverage, and no output schema, the description provides sufficient context. It covers purpose, output, and relationship to sibling tool.

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

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

Schema coverage is 100% with clear descriptions for both parameters (limit and query). The description does not add additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Search', the resource 'City of Montreal open-data catalogue', and the output 'title and its queryable datastore resource ids'. It distinguishes from sibling tools like montreal_query by mentioning that the ids can be used with that tool.

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

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

The description implies when to use the tool (to search datasets by keyword) and how to chain it with montreal_query. However, it does not explicitly state when not to use it or compare directly with siblings like montreal_recent.

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, non-destructive. Description adds that it queries datastore resources and supports various query options. However, it does not disclose return format or pagination details beyond limit/offset, which are already in the schema.

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

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

Two well-structured sentences. First sentence captures core purpose and source. Second lists capabilities and links to sibling tools. No wasted words, front-loaded with critical 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?

Covers how to use, which parameters, and how to find the required resource ID. Missing return value description, but the tool is straightforward. Given no output schema, a brief note on response format would improve completeness.

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

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

Schema coverage is 100% so baseline is 3. Description summarizes but does not add significant meaning beyond the schema's own parameter descriptions. It reinforces the syntax and purpose but lacks deep additional context.

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

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

Clearly states it queries any City of Montreal datastore resource by resource ID. Lists supported features (free-text, filters, sort, limit, offset). Distinguishes from siblings by directing to montreal_datasets and montreal_recent for finding IDs.

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

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

Explicitly instructs to use montreal_datasets or montreal_recent to obtain resource IDs, telling the agent when not to use this tool directly. Also explains the parameters briefly, giving clear context for usage.

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

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

Annotations already provide safety info (readOnlyHint, idempotentHint, etc.). Description adds useful context like 'Returns the latest rows (newest-first)' and explains the free-text filter via `q`. No contradictions. However, it could mention pagination or error handling but overall sufficient.

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 earning its place: purpose, usage guidance, and parameter info. No extraneous text. Front-loaded with key 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 only vaguely states 'returns the latest rows'. It doesn't specify return format, error handling, or rate limits. However, the tool is simple and annotations cover safety. For completeness, mention of output structure would be helpful, so a 3 is appropriate.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that `q` is a free-text filter across all columns and lists dataset enum values. Examples further clarify usage. This goes beyond the raw 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 retrieves 'recent records' from a specific source (Montreal open dataset) and lists exact datasets (311, crime, permits). It distinguishes itself from the sibling tool 'montreal_query' by stating 'for full control use montreal_query', so the agent knows when to use which.

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 the agent to 'PREFER OVER WEB SEARCH' for certain queries, and contrasts with 'montreal_query' for full control. This provides clear guidance on when to use this tool versus alternatives.

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

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

All annotations are false, so the description carries full behavioral burden. It discloses the claim_token flow (no account returns a token; passing it back reads status/changes), daily rate limit, free/no-quota status, and that the team reads digests daily. This goes well beyond the annotations and gives the agent a realistic model of the tool's behavior.

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

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

The description is long but not bloated; each sentence earns its place by covering usage scope, exclusions, claim-token mechanics, and rate limits. It front-loads the purpose in the first sentence. Although formatting as a single dense paragraph slows scanning, the density of genuinely useful information keeps it 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?

For a tool with no output schema and a moderate parameter count (including a nested context object), the description covers all necessary context: when to use, when not to use, how the claim token lifecycle works, rate limiting, and data privacy guidance (don't paste end-user prompts). The absence of an output schema is compensated by describing claim_token returns and resolution behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds critical semantics for claim_token (pass with no other arguments; returns status and resolution details) and message (be specific, 1-2 sentences, 2000 chars max), which the schema does not fully convey. The other parameters are already well-described in the schema, so this modest additional value justifies a slight above-baseline score.

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

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

The description opens with a specific verb+resource ('Tell the Pipeworx team...') and clearly enumerates the feedback categories (bug, feature/data_gap, praise). It distinguishes itself from sibling research and subscription tools by framing it as feedback about Pipeworx tools specifically, not data lookups or agent operations.

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

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

Explicit when-to-use guidance is given for each category (broken/wrong data, missing tool, praise), and a clear exclusion is stated: report only tools served by this Pipeworx connection, not tools from other MCP servers. It even tells the agent to file with that other server instead, which is stronger exclusion guidance than most tool descriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h. This provides supplementary context without contradicting annotations.

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

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

The description is dense but well-structured: a one-sentence summary, a bulleted list of use cases, and technical details. Every sentence adds value. It could be slightly shorter, but remains 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 the tool's simplicity (1 optional parameter, no output schema), the description fully covers what is returned, data source, caching, and use cases. Nothing missing for effective 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?

The single parameter 'window' has enum values explained in the description as 'shorter windows surface what's hot right now; longer windows show steady-state demand', adding semantic guidance beyond the schema. Schema coverage is 100%, but the description enhances 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 returns 'top tools, top packs, and total call volume over a recent window', using specific verbs and resources. It differentiates from siblings like 'discover_tools' by focusing on what other agents are currently calling, making its purpose distinct and easy to understand.

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?

Three explicit use cases are listed (discovering hot sources, confirming popular tools, aligning with agent needs), providing clear guidance on when to use. It lacks direct comparisons to alternative tools, but the context implies when not to use (e.g., for specific queries). Caching details also inform behavior.

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

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

The description adds significant context beyond annotations (readOnlyHint, etc.), detailing the algorithmic steps (semantic anchor, partition filter, fill check). 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 dense with technical details but well-organized (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). However, slightly verbose; a trim could improve conciseness without losing critical info.

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

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

Covers all aspects of a complex tool: scanning modes, algorithmic checks, fill analysis, and response structure. No output schema provided, but the description compensates thoroughly.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: 'event' accepts slugs or URLs, 'topic' is a seed question, and it explains the behavioral difference (cross-event scanning). This adds clear value.

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

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

The description clearly defines the tool's purpose: finding arbitrage via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event, topic) with specific verbs and resources (e.g., 'call with NO args', 'pass event', 'pass topic').

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, including when not to trade ('realizable_edge_pp ≤ 0 means... do not trade it') and a pointer to an alternative tool ('For custom sizing use polymarket_fill_risk'). This helps the agent select correctly.

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

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

The description discloses extensive behavioral traits: three model families, segment groupings, edge calculations (edge_pp_net, kelly_fraction), tradeable-edge knobs, caching at KV level, diagnostics for empty segments. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds substantial context beyond them.

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

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

The description is comprehensive but verbose; it could be shortened without losing key information. It is front-loaded with purpose, but the detailed model family explanations and caching behavior make it longer than 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?

Given no output schema, the description thoroughly documents response structure (by_segment, fed_candidates, _diagnostics), edge attributes, and filter behaviors. With zero required parameters and complex nested segments, the description provides sufficient context for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds significant meaning for parameters like slippage_pp (justifying default of 0.3 based on Polymarket's zero fees but bid/ask costs), min_partition_leg_kelly (explaining how it applies to partitions), and min_liquidity (warning about walking the book). This extra context raises the score.

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 top Polymarket markets to return opportunities where Pipeworx data disagrees with market price, positioning it for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx-model-driven edge detection from top markets.

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 mentions agents discover opportunities without paging hundreds of markets, providing clear usage context. It does not explicitly state when not to use or list alternatives, but the purpose is well-defined for edge-seeking agents.

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 annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining trend types and decay semantics, disclosing limitations (60-day TTL, no intraday data), and clarifying data gaps. This provides comprehensive behavioral context beyond the read-only and 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 detailed but well-structured, starting with the core purpose, then explaining parameters, and finally the response blocks. While slightly verbose, every sentence adds necessary information for a tool with no output schema, making it efficient given 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?

For a tool with no output schema, the description thoroughly covers the response structure, edge cases (gaps, expired items), limitations (TTL, no intraday), and interprets negative values. It provides sufficient context for an agent to understand and 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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining how the 'window' parameter selects snapshot families ('24hr | 1wk | 1mo') and how 'days' controls lookback, along with defaults. It also contextualizes parameters within the broader tool function, though it largely reiterates the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It uses specific verbs and resources ('answers how long has this edge existed and is it shrinking') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description implies usage context by contrasting fresh edges with old ones and referencing polymarket_edges as the data source. However, it does not explicitly state when to use this tool versus alternatives or provide clear exclusion criteria, so it loses a point for not offering explicit when-not 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, and not destructive. The description adds critical behavioral details: it walks the order book ladder, returns a verdict (clean/degraded/cannot_fill), and cautions that theoretical overround on thin books is not capturable, and partial fills create directional risk.

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 structured: uses bold labels, lists, and separate sections for single-market and basket. While slightly lengthy, every sentence adds value and is not redundant. It could be slightly more concise without loss of 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?

No output schema exists, but the description compensates by enumerating all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also addresses edge cases and failure modes, making it fully actionable.

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

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

Schema coverage is 100% with good descriptions, but the tool description adds substantial extra meaning: explains the difference between single-market and basket parameter behavior, clarifies the auto-default for side in basket mode, and describes size_usd meaning in each mode (spend vs target proceeds for single-market, settlement notional for basket) along with clamp range.

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 checks realizable vs theoretical edge using order book depth, with two distinct modes (single-market and basket). It distinguishes from sibling tools like polymarket_arbitrage, making the purpose unambiguous.

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

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

Explicitly states when to use: before polymarket_arbitrage signals or polymarket_edges trades above $500. Also warns against using without risk understanding, and explains the danger of partial basket fills converting arb into directional position.

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 cover read-only/idempotent safety, but the description adds substantial behavioral disclosure: compatibility_codes semantics, the fact that warnings can be non-empty even when matched_pairs>0, the null meaning of temporal_alignment, gross-vs-net fee treatment, skipped counter definitions, and the explicit 'not modeled' fee limitation. This goes far beyond what annotations alone communicate.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loaded purpose. Almost every sentence carries distinct information, though a few code definitions and counter explanations could be tightened without losing value.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, spread direction, top_spreads_pp, safety codes, compatibility flags, temporal alignment, fees_note, skipped counters, and low_confidence_pairs. An agent has enough to call the tool and interpret its results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that `topic` auto-fetches a matching event per venue, that explicit tickers override the topic-mapped side, and that both modes run the identical token-overlap matcher with the same disclosures. These relationships are not fully captured by the 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?

Opens with a specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' identifying the exact resource and operation. It clearly differentiates this tool from same-venue alternatives by emphasizing 'cross-venue' and the token-overlap matcher for 'the same resolving question.' The two modes are explained up front, leaving no ambiguity about what the tool computes.

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 strong within-tool guidance: two clearly described modes, when to use `topic` vs explicit tickers, and an explicit warning that 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility_warning today. It does not explicitly name sibling alternatives or state when to prefer e.g. polymarket_arbitrage over this tool, so it stops short of full alternative routing.

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, not destructive. Description adds scoping info, which is useful 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?

Three concise sentences: operation, use case, scope and pairing. Front-loaded with core 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?

Covers operation, listing, scope, and usage context. Lacks details on return format, but acceptable for a simple read tool with no output schema.

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

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

Schema coverage is 100% and schema already describes the parameter's behavior. Description reinforces the 'omit to list' behavior but doesn't add new 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 retrieves a value saved via remember or lists all saved keys. It distinguishes from siblings by explicitly mentioning '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?

Provides explicit context for use: look up stored context without re-deriving. Mentions pairing with remember and forget, and 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?

The description adds behavioral context (returned fields, filtering, polling) but contradicts the readOnlyHint annotation by describing a state-modifying mark_read parameter. This inconsistency undermines trust despite otherwise useful details.

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?

Four sentences, each serving a purpose: main action, output description, filter options, mark_read behavior, alternative access. No redundant words, front-loaded with the primary function.

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 explains return fields (source, citation_uri, payload) and covers all key use cases. Missing minor details like pagination, but sufficient for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for all parameters: type (subscription type), since (ISO timestamp), mark_read (flag as read), unread_only (null read_at). It explains behavior beyond the schema's descriptions.

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

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

The description starts with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes from sibling tools like list_subscriptions and subscribe/unsubscribe by focusing on event retrieval rather than subscription management.

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

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

The description provides clear context for usage: it returns recent alerts, supports filtering by type and timestamp, and mentions that polls work fine. It also points to an alternative endpoint for scripts, but does not explicitly state when not to use this tool or compare with 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?

The description details fan-out behavior, fallback from GDELT to GNews, soft-fail of USPTO, and return structure (changes grouped by source, total_changes count, citation URIs). Annotations already convey safety, but description adds significant behavioral 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?

Description is efficient, starting with query examples, then fan-out logic, parameter notes, and return structure. Every sentence serves a purpose, 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?

Despite no output schema, description explains return format and cites behavior for each source. Lacks details on error handling or empty results, but covers main functionality and integration points well.

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?

100% schema coverage provides baseline of 3, but description adds value by explaining 'since' accepts relative shorthand (e.g., '7d', '30d'), value accepts ticker or CIK, and type is limited to 'company'. Examples like '30d' for typical monitoring enhance usability.

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 across multiple sources (SEC, GDELT/GNews, USPTO) with specific examples, and explicitly distinguishes it from the sibling tool entity_profile, which returns static profiles.

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

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

The description gives clear context for when to use this tool ('What's new', 'latest on Y') and explicitly mentions entity_profile as an alternative for static profiles. It lacks explicit 'when not to use' but the alternative sufficiently guides usage.

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

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

Annotations provide idempotent and non-destructive hints. Description adds scoping, retention policy, and user-based persistence, complementing annotations well. Could mention overwrite 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?

Compact description covering purpose, usage, pairing, and persistence. Slightly dense but earns its sentences.

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

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

For a simple 2-param tool with no output schema, the description covers all essential aspects: what it stores, scope, retention, and pairing with related tools.

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 clear descriptions. Description adds valuable examples of key/value usage, enhancing semantic 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?

Clearly states the tool saves data for reuse later with concrete examples (ticker, address, preference, subject). Distinguishes from siblings 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') and mentions alternatives (recall, forget). Also explains persistence details.

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, disclosing that enrichment degrades gracefully when GLEIF or OpenFIGI is unavailable, that ambiguous matches assert nothing and return figi_candidates, that unresolved identifiers are explicitly listed, and that each call cascades through multiple lookup endpoints. These behaviors are not visible in the annotations or schema and materially affect how an agent should interpret results.

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 purpose and usage, and nearly every sentence adds operational detail. Some parenthetical expansions could theoretically live in supporting docs, but given the tool's complexity and the lack of an output schema, the length is justified rather than wasteful.

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

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

For a tool with two parameters, high internal complexity, and no output schema, the description is remarkably complete: it covers accepted inputs, sources, fallback behavior, ambiguity handling, unresolved-identifier reporting, ISIN-to-LEI mapping, and drug return contents. An agent has enough context to invoke it correctly and interpret its results.

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

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

Although schema coverage is 100%, the description adds substantial semantics: value formats, accepted identifiers for company input, brand/generic names for drug input, corrected examples like 'ozempic' vs 'metformin', and a critical anti-pattern warning about trailing security-class words in bond issuer names. This meaningfully exceeds the schema's minimal parameter descriptions.

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

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

The description states a specific verb ('resolve'), a clear object ('a user-spoken NAME to the canonical/official identifiers'), and enumerated supported types with concrete examples like tickers, CIKs, LEIs, and RxCUIs. It clearly differentiates itself from lookup tools by emphasizing that it produces identifiers other tools require as input, and scopes its domain to company and drug entities.

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

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

It explicitly instructs the agent to 'Use FIRST whenever you have a name but need an ID,' which is direct usage guidance. It also provides alternative-shaped examples, explains when ambiguity should return candidates rather than a single assertion, and gives precise input-format rules such as passing the issuer name exactly as printed and never the full noun phrase.

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. The description adds behavioral details: it probes each entity with 'ai_visibility_check', ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. 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 four sentences, each serving a purpose: main action, internal mechanics, use case, and return structure. It is front-loaded with the core purpose and avoids redundancy. 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also mentions that it uses 'ai_visibility_check' internally, which helps set expectations. For a composite tool with 4 parameters, this is complete enough to guide an agent.

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

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

Schema has 100% parameter description coverage. The description adds meaning beyond schema by explaining that the first entity in 'entities' is treated as the 'subject' for narrative, and mentions the 'context' parameter disambiguates common names. This provides richer semantics for key parameters.

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

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

The description clearly states the main action ('Compare AI visibility across multiple entities side-by-side'), with specific verb and resource. It distinguishes from siblings like 'ai_visibility_check' by describing it as a composite tool that ranks entities. The concrete example question 'does Claude know about us as well as our competitors?' solidifies purpose.

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

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

The description explicitly says 'Useful for competitive AI-marketing audits' and provides a scenario. It implies when to use (comparison of multiple entities). Does not explicitly state when not to use or name alternative tools, but the context is clear enough for an AI agent to infer correct usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. Description adds critical behavioral details: it fans out across two external services, bundlephobia's first measurement can take 5-30s, and partial failures degrade gracefully with sources_failed reporting. 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 packed with information in a single paragraph, efficiently stating purpose, use case, return structure, ecosystem limits, and edge cases. While dense, it is well-organized and every sentence contributes useful detail.

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

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

Despite no output schema, the description details the return structure (summary fields, advisories, links, alternative versions) and explains error handling with partial failures. Covers all relevant behavioral aspects for agent invocation.

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

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

Input schema covers both parameters with descriptions. The description adds value by noting that scoped packages (e.g. '@types/node') are accepted and that the version parameter defaults to the latest. Schema description coverage is 100%, so a baseline of 3, but the added context lifts it to 4.

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

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

The description clearly states it is a composite check for evaluating whether to add an npm package, covering license, advisories, bundle size, and more. It distinguishes itself by specifying NPM-only scope and directing other ecosystems to separate tools.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes ecosystem limitations and alternative paths for non-NPM packages, providing clear when-to-use and alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds significant behavioral details: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, 200K character cap with truncation flagging.

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

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

The description is concise and well-structured: first sentence gives core purpose, second gives usage guidance, third gives technical details. Every sentence contributes 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?

No output schema exists, but description explains return format (passages with offsets and scores) and covers input constraints (200K chars, truncation). Sufficient for a search tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by providing examples for the query parameter and noting the 200K char limit for the text parameter, explaining truncation behavior.

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

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

The description clearly states it performs semantic search inside a fetched record. It specifies the verb 'search' and resource 'a source' (record), and distinguishes itself from siblings by noting it pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Also provides alternative approach by mentioning pairing with ask_pipeworx_grounded, giving clear usage context.

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

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

Adds significant behavioral details beyond annotations: phone verification for SMS, 10/day cap, webhook signing secret returned once, auto-disable on failure. Annotations already indicate non-read, non-destructive, and idempotent, and description aligns with these.

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?

Well-structured with core purpose upfront. Contains necessary detail but could be slightly more concise by separating type-specific notes. Overall 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?

Completely covers prerequisites, types, delivery options, constraints, and return value. No output schema, but return is mentioned. For a complex tool with nested objects, this is fully adequate.

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 description adds rich examples and constraints for each parameter, especially for params (type-specific filters) and delivery (detail on SMS, email, webhook). Enhances 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?

Description clearly states the tool creates a proactive monitoring subscription and returns a subscription id, using specific verbs and resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context on required account type (Pipeworx OAuth), supported types, and delivery channels with constraints. Does not explicitly state when not to use or alternatives, but the context is sufficient for an AI.

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. Description adds value by detailing the output format (category-bucketed questions with tool+argument shape) and that calling with no arguments gives full spread.

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?

Well front-loaded with alternative phrasings and purpose. Every sentence adds value, though the list of categories is slightly long. 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?

For a simple tool with one optional parameter, the description covers purpose, usage, output structure, and linkage to other tools. No gaps given the lack of output schema.

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

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

Schema coverage is 100% and describes topic as optional focus area. Description reinforces this with examples of valid values ('finance', 'pharma', etc.) and explains the result of omitting vs. specifying a topic.

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 category-bucketed example questions and explicitly frames it as the onboarding entry point. It distinguishes from siblings like 'discover_tools' by specifying it's the first tool to use when unsure.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions optional topic filtering. Lacks explicit when-not-to-use instructions but provides strong 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?

The description adds behavioral context beyond annotations, such as ownership enforcement and deactivation behavior (not deletion), ensuring historical events remain available via recent_alerts. This aligns with annotations: readOnlyHint false, destructiveHint false, idempotentHint true.

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

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

Two sentences, front-loaded with the primary action, and no wasted words. The information is efficiently presented.

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

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

For a simple cancellation tool with one parameter and no output schema, the description provides sufficient context including ownership enforcement, deactivation behavior, and impact on historical data.

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 mentions 'by id' which is consistent with the schema. No additional detail is needed beyond what the schema provides.

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

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

The description clearly states 'Cancel a subscription by id' which is a specific verb and resource. 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 explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and explains that the row is deactivated not deleted, guiding when to use the tool and what consequences to expect. However, it does not explicitly list when not to use it or mention alternatives beyond 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?

The description goes beyond annotations by detailing the two processing paths (SEC EDGAR/XBRL and grounded pipeline), the exact verdict values, and the crucial distinction between 'could_not_verify' and 'unsupported'. This is especially valuable because annotations only indicate read-only/idempotence, not these operational nuances.

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

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

The description is long but each sentence contributes. It opens with natural-language trigger examples, states purpose, covers two paths, return values, and critical caller caveats. While some could be tightened, the structure (general → specific → caveats) is logical and the warnings are essential.

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

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

For a tool with 2 parameters and no output schema, the description is highly complete: it explains routing logic, verdict semantics, evidence citations, and error handling (verification_error). The only missing piece is a formal output schema, but the description compensates by listing the return fields.

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

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

The schema covers 100% of parameters with detailed descriptions, including tolerance_pct semantics and examples for claim. The description adds only marginal value by mentioning 'exact percent-delta math' for financial claims, but the parameter-level guidance is already present in the schema. Thus 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 validates natural-language factual claims against authoritative sources, with explicit example phrasings ('Is it true that…', 'fact check'). It distinguishes itself from siblings by focusing on claim verification, and explicitly mentions replacing multiple sequential calls.

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

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

It gives clear context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains routing for company-financial vs other claims. However, it doesn't explicitly mention when not to use it or compare to specific alternative tools like ask_pipeworx_grounded.

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