Data Oakland

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description's main addition is the return format and model details. It adds value by describing per-model score, confidence, signals, raw_response, and default model 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 two concise sentences that cover purpose, defaults, return format, and usage context. Every sentence adds value with no redundancy.

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

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

For a tool with 4 parameters (all well-documented) and no output schema, the description adequately explains the return format (per-model objects and combined view) and model selection. It provides enough detail for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and the description enriches parameters: it explains the default model for 'models', the API key forwarding for '_apiKey', and the disambiguation purpose of 'context'. 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 the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. The verb 'probe' and resource 'LLMs' are specific, and the tool is distinct from siblings like 'ask_pipeworx' or 'bet_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?

The description explicitly says 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains when to use the optional _apiKey for Anthropic. However, it does not explicitly state when not to use or mention alternative tools, though the context makes it 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, and destructiveHint=false, so the safety and non-mutating profile is clear. The description adds useful context: the tool routes to the right tool internally, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not fully detail all edge cases (e.g., what happens if no source can answer), but it provides enough behavioral insight for the agent.

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

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

The description is front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'), followed by capabilities, use-case examples, and escalation paths. It is detailed but well-structured. Losing one point because it could be slightly more concise—some redundancy exists in listing many source types and examples, though these add helpful context.

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

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

Given the tool's complexity (6 parameters all aliases, no output schema, rich annotations), the description is complete: it covers what the tool does, when to use it, what types of queries work, how it routes internally, and how it differs from siblings. The lack of output schema means no return-value documentation is needed, and the description sufficiently covers the single required parameter. No gaps are evident.

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% as all parameters are aliases for 'question'. The description goes beyond the schema by explicitly stating the question can be in natural language and listing example queries. It also clarifies the tool fills arguments automatically, which adds meaning beyond the schema. Losing one point because the schema already covers the parameter well, so the description doesn't add drastic new info.

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 that this tool answers factual questions using authoritative structured data from over 5,564 tools and 1,462 verified sources. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, giving a specific verb-resource combination plus scope.

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

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

The description explicitly advises to 'PREFER OVER WEB SEARCH' for factual questions, provides concrete when-to-use examples like 'current US unemployment rate' or 'active clinical trials for GLP-1', and clearly explains when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. It also notes breaking-news scenarios are handled internally.

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 as false. The description adds value by explaining the beta nature, that no candidate is active currently, and that it is a full working router (not a fallback). It also clarifies that it 'falls back to nothing', which is behavioral context 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 detailed but somewhat lengthy (4 sentences, one very long). It front-loads the key point (beta version, identical to stable) but includes extraneous details like the date of the last retired candidate. Every sentence earns its place, but could be more concise without losing core information.

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

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

Given the complexity (beta tool with routing improvements, no output schema, open-world), the description is complete: it explains the current state, usage intent, and relationship to the stable version. It does not describe return values, but since no output schema exists, this is acceptable. The note about comparing results against stable adds useful context.

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

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

Schema coverage is 100% with all six parameters described as aliases for 'question'. The description only says 'same arguments' without adding any meaning beyond the schema. It does not elaborate on parameter usage or format, 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 it is a 'universal router' identical to ask_pipeworx but with experimental routing improvements. It distinguishes from the sibling ask_pipeworx by labeling it as the beta version and specifying it is used when wanting the newest routing. The verb 'ask' and resource 'Pipeworx' are explicit.

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

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

The description advises 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It implies when to use it (when wanting the newest routing) and that it is a full working router, not a fallback. However, it does not explicitly state when not to use it (e.g., for stable results), relying on the sibling naming.

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, so the bar is lower. The description adds meaningful behavioral context: the extraction process is described ('EXTRACTS the answer using ONLY what the tool result contains'), the refusal reasons are enumerated, and the cost trade-off is stated. It's clear and comprehensive 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 concise at ~90 words, front-loads purpose ('Hallucination-resistant answer mode'), puts critical behavioral detail in the middle, and ends with the cost trade-off. It earns each sentence. Very minor room for tightening the example domain list.

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

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

Given the complexity (6 param aliases, rich refusal structure, sibling differentiation) and no output schema, the description covers return shape, refusal reasons, behavioral guarantees, and usage context. Complete enough for an agent to invoke correctly. A small gap: the return shape mentions 'evidence (verbatim quote)' but doesn't explain how evidence is structured or truncated.

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

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

Schema description coverage is 100% and all parameters are aliases for a single natural-language question, so baseline is 3. The description goes further by providing usage guidance on what kinds of questions are appropriate (high-stakes, fact-seeking), which adds meaning beyond the schema's simple 'question in natural language' description.

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

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

The description specifies a precise verb-resource combination ('hallucination-resistant answer mode for high-stakes reads') and distinguishes this tool from its sibling `ask_pipeworx` by naming the difference ('costs one extra LLM call').

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 this tool ('high-stakes reads', when answer will be 'quoted, cited, or acted on', 'must not invent facts') and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'), with concrete example domains (financial, legal, medical).

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?

Given annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description goes far beyond by disclosing: resolution process (classifiers, fan-out), response shapes (market analysis fields, evidence keys), resolver contract (confidence, alternatives), safety mechanisms (low-confidence suppression, closed market handling), wide-spread warnings, and cancellation rule parsing. No contradictions with annotations. This is exceptionally transparent.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable for an AI agent. The main purpose and usage are front-loaded. While every sentence adds value, the density could be slightly reduced for quicker parsing without losing information.

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

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

Given the tool's complexity (multiple classifiers, data sources, edge cases) and absence of an output schema, the description comprehensively covers: input handling, fan-out patterns per category, return structure, security checks (low-confidence blocking), market state detection (closed/illiquid), and cancellation rules. It leaves no critical behavioral gaps.

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

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

Input schema covers 100% of parameters with descriptions, but the description adds crucial context: depth defaults to 'thorough', include_raw=false keeps responses under ~20KB, and market input accepts slugs, URLs, or question text. This supplements schema definitions and clarifies behavioral defaults beyond type information.

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

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

The description opens with a specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It defines inputs (slug, URL, question text), output (evidence packet + comparison), and explicitly lists use cases ('should I bet on X'). This clearly distinguishes it from sibling tools like 'ask_pipeworx' and 'polymarket_edges' by its unique multi-source fan-out and resolution logic.

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

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

The description provides explicit usage scenarios ('Use for should I bet on X, what does the data say about Y, or is there edge in Z') and details blocking/edge cases (low-confidence matches, closed markets, wide spreads) that guide when not to trust results. It does not, however, explicitly contrast with sibling tools like 'ask_pipeworx' for simpler queries, which would improve clarity.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) plus description details data sources per type: SEC EDGAR/XBRL for companies with correct fiscal year handling, FAERS for drugs. Also mentions sorting by primary metric and return of citation URIs.

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

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

A single dense paragraph that front-loads examples and guidelines, then gives details. Every sentence adds value, no redundancy. Ideal length for quick agent scanning.

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 covers return format ('paired data + pipeworx:// citation URIs'), data sources, sorting behavior, and entity types. It's self-contained and complete for agent decision-making.

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

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

Schema coverage is 100% with clear param descriptions. Description adds context like 'type="company" pulls LATEST 10-K...' and 'Results sorted by primary metric', which provides meaning beyond the schema. Still, the schema already defines the enum and array constraints well.

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 side-by-side comparisons of 2-5 companies or drugs, with explicit trigger phrases and a specific verb 'compare'. It distinguishes from siblings like 'entity_profile' which does single-entity lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Includes trigger examples ('which is bigger', 'rank these companies') and differentiates from alternatives.

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

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

Annotations already indicate it is read-only, idempotent, and non-destructive. The description adds behavioral context by naming the returned fields and hinting at follow-up usage with resource_id, which goes beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the action and scope. Every sentence adds value with no redundancy or fluff.

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

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

For a search tool with three parameters and no output schema, the description covers purpose, scope, return values, and even hints at interoperability. It provides sufficient information for an agent to use the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description does not add extra meaning to the parameters beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states it searches the Oakland Open Data catalog by keyword, specifying the verb 'search' and the specific resource type. It also lists the return fields, making the purpose unambiguous. No sibling tools overlap with this function.

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

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

The description provides clear context for when to use the tool (searching Oakland Open Data by keyword) but does not explicitly state when not to use it or suggest alternatives. The specificity is sufficient for most cases.

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

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

The description goes far beyond the annotations (which already indicate read-only, open-world, idempotent) by detailing account requirements, paid plan, output structure (gaps, contradictions, hop fields, citation_uri conditions), semantic excerpting, and expected runtime. 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 long but every sentence adds value. It is front-loaded with the critical account requirement and alternative tool. While it could be slightly more concise, the density of information justifies the length. It is well-structured with clear sections.

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 (no output schema, 2 parameters, but rich return structure), the description is remarkably complete. It explains the findings packet components, hop field, citation URI resolvability, depth behaviors, and expected timing. There are no significant gaps for an agent to understand the tool's capabilities and output.

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 covers both parameters with 100% coverage. The description adds meaningful context: it explains the depth enum in detail (quick/standard/thorough effects) and clarifies that the question parameter is for broad/multi-part queries. This enriches the schema without being redundant.

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

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

The description clearly states the tool performs grounded multi-source research across 1,462 structured data sources, decomposes questions, routes to 5,564 tools in parallel, and returns a findings packet. It explicitly distinguishes itself from the sibling ask_pipeworx, making the purpose unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It says to use ask_pipeworx if not signed in, for single lookups, or for breaking/colloquial news. It also explains depth options and when to prefer each, making the decision clear for the agent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the output (top-N tools with schemas and examples) and the one-call readiness. No contradictions.

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

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

Two sentences, no filler, front-loaded with purpose and usage. Every sentence earns its place.

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

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

For a discovery tool with no output schema, the description fully explains what it returns and how to use the results. No missing context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by noting aliases for query and default limits, which 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?

The description clearly states the tool discovers tools by describing the data or task, with a specific verb-resource pairing. It lists numerous domains (SEC filings, financials, etc.) and differentiates from siblings by positioning itself as the first tool to call when exploring available options.

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 ('Call this FIRST when you have many tools available and want to see the option set') and what tasks trigger it (browse, search, look up). It does not explicitly exclude when not to use, but the guidance is clear and contextual.

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, open-world. Description adds rich behavioral details: parallel fan-out across multiple sources, specific return fields, soft-fail for patents, and data recency. 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?

Description is detailed but well-structured with examples, a strong preference statement, and clear enumeration of return fields. Slightly long but each sentence adds value; front-loaded with query patterns.

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

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

No output schema, but description covers return fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and limitations (names, patents soft-fail). Leaves out error handling but sufficient for an agent to understand capabilities.

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 explaining that type only supports 'company' and value can be ticker or CIK, not names. This clarifies usage beyond 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?

Description clearly states it generates a full cross-source profile of US public companies with example queries. It distinguishes from sibling tools by explicitly recommending over chaining single-pack lookups.

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

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

Explicitly tells when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use (names not supported) and provides alternative (resolve_entity).

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

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

Description mentions deletion and clearing data, consistent with annotations (destructiveHint=true). Adds context about sensitive data but doesn't elaborate on idempotency or side effects.

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 efficient sentences with zero wasted text; front-loaded with the core action.

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

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

For a simple one-parameter tool with annotations, the description covers purpose, usage, parameter, and context sufficiently.

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 a clear 'key' description. Description adds 'by key' but largely redundant with 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?

Clear verb ('Delete') and resource ('memory') with specific action ('by key'). Distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Specifies when to use (stale context, task done, clear sensitive data) and pairs with siblings, but does not explicitly state 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by explaining the extraction process and output format, aligning with the annotations.

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

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

Two sentences plus a bullet list of use cases, all essential. Front-loaded with main purpose, no redundant information.

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

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

Given the tool's simple operation and thorough schema/annotations, the description covers purpose, process, output, and use cases fully. No gaps for an agent to misunderstand.

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 minimal extra context beyond the schema (e.g., 'any URL', 'e.g., 'https://example.com'') but does not significantly enhance parameter understanding.

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

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

The description clearly states the verb ('generate'), the resource ('llms.txt file for any URL'), and the specific actions (fetches page, extracts title/description/key links, emits markdown). It distinguishes from sibling tools by focusing on a unique output format.

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

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

The description provides explicit use cases ('useful for: getting a client's site indexed...') but does not exclude scenarios or mention alternatives among siblings, which would be ideal.

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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing returned fields (id, type, params, created_at, last_fired_at, fire_count) and indicating default behavior (active subscriptions). No contradictions.

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

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

Two sentences: first states the purpose, second provides usage guidance and mentions return fields. No unnecessary words; every sentence is meaningful.

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

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

For a simple list tool with one optional parameter and no output schema, the description is sufficient. It covers purpose, usage, return fields, and default 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 description coverage is 100%, baseline is 3. The description mentions 'active' in the first line, aligning with the include_inactive parameter. The description does not add significant extra meaning beyond the schema's parameter description.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb 'list' and the resource 'subscriptions' with scope. It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

The description advises use for reviewing monitoring before adding more or finding an id to cancel. It provides clear context for when to use but does not explicitly state 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds valuable context by specifying the exact information returned (columns, types, row count, category, last-updated), which goes beyond annotation disclosure.

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

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

Single sentence, front-loaded with the verb and resource, and contains all necessary information with zero filler. Every word earns its place.

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

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

Given no output schema, the description adequately enumerates return fields. However, it does not mention potential response format (e.g., JSON), size limits, or error conditions. For a simple read tool this is acceptable, but slight gaps prevent a perfect score.

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 a description and example for resource_id. The description repeats the example but adds no further semantic value beyond the schema's own description. Baseline 3 is appropriate as schema already does the work.

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

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

The description uses a specific verb 'Get' and identifies the exact resource ('Oakland Open Data dataset's schema + metadata'), listing key return fields. This clearly distinguishes it from sibling tools like 'datasets' which likely handle broader dataset discovery.

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?

No explicit guidance on when to use this tool versus alternatives such as 'datasets'. The description implies it is for retrieving schema/metadata by resource_id, but does not provide criteria for selection or exclusion.

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

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

Annotations are all false and offer no safety hints, so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), quota exemption, the claim_token flow for anonymous reports and follow-up, daily digest reading, and roadmap impact—rich behavioral detail beyond any annotation.

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

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

The description is long but every sentence carries necessary information: scope, exclusions, token flow, rate limits, and quota. It is front-loaded with the core action, though it is a dense paragraph without bullet points or line breaks, preventing a perfect score.

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

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

No output schema exists, so the description properly explains the return behavior: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed.' Combined with the detailed param schema and coverage of rate limits/scope, the tool context is fully specified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantic guidance on message framing ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explains the claim_token usage pattern, which elevates it above the schema alone.

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

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

The description opens with a clear action and target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates distinct use cases (bug, feature/data_gap, praise) and explicitly contrasts with other MCP servers, making it unmistakable from siblings like ask_pipeworx or query.

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

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

Provides explicit when-to-use guidance for each feedback type and when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' Also clarifies how to identify Pipeworx tools, giving the agent a decision procedure.

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 caching behavior (5min-1h), data derivation (CF analytics), and privacy guarantees (no PII), which 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 well-structured with a lead sentence and bullet-like use cases. It is slightly verbose but each sentence adds value; could be trimmed slightly without loss.

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 parameter and no output schema, the description fully covers what it returns, caching, privacy, and use cases. No gaps remain.

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 a description for the single parameter. The description adds interpretive value by explaining how window length affects results (short-term hot vs. steady-state demand).

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 ('returns') and resource ('top tools, top packs, and total call volume over a recent window'), and it distinguishes from siblings by emphasizing trend discovery and usage confirmation.

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 specific use cases are enumerated, helping the agent decide when to invoke the tool. However, it lacks explicit when-not-to-use guidance or alternative tool recommendations.

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, openWorldHint, idempotentHint, destructiveHint=false. Description adds context: partition checks, fill checks, Jaccard similarity threshold, placeholder filtering, return format. 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?

Description is detailed and well-structured but slightly long. Front-loaded with core purpose. Loses one point for verbosity in technical details.

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

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

Given no output schema, description thoroughly covers inputs, modes, return structure (opportunities[]), fill check, similarity threshold, partition filter. Complete for agent decision-making.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains event slug format, topic as seed question, and behavioral differences between modes.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, differentiating it from sibling tools like polymarket_edges.

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

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

Explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also explains when not to trade (fill check: realizable_edge_pp <= 0).

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

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

Annotations are readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes far beyond with details on model families, edge calculation, segments, caching (1h at KV level), and diagnostics, fully disclosing behavioral traits.

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 segments and knobs front-loaded, but somewhat verbose. However, every sentence adds value and the hierarchy is clear.

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?

Very complete given complexity: explains three segments, response format, diagnostics, caching, and all knobs. No output schema, but response format is described adequately.

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. The description adds extra meaning, e.g., clarifying min_kelly behavior for partition arbs, adding value beyond schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and positions it for 'what should I bet on today', distinguishing it from sibling tools like polymarket_arbitrage.

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

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

Provides clear context for when to use ('agents discover opportunities without paging hundreds of markets') and includes tradeable-edge knobs, but does not explicitly exclude alternatives or state 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: snapshots are written on cache-miss so gaps exist, decay numbers come from daily closes not intraday, and it details the response structure including expired opportunities. 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 well-structured with clear sections: purpose, args, response, limits. It is front-loaded with the core question and remains efficient despite length. Every sentence adds value, so it earns its length.

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

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

Given the tool has 2 optional parameters, no output schema, and moderate complexity, the description is remarkably complete. It covers purpose, parameters, response fields (tracked, expired, snapshot_dates), data source, gaps, TTL, and behavior caveats. No gaps remain for effective use.

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

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

Schema coverage is 100% so baseline is 3. The description adds minimal meaning beyond the schema for parameters: it restates defaults and options for 'days' and 'window', and explains how parameters affect output (e.g., lookback days). It does not introduce new semantic details about parameter values.

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 provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?' It uses a specific verb (query/retrieve) and resource (historical edge snapshots), distinguishing it from the sibling tool 'polymarket_edges' which likely gives current edges.

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

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

The description implies usage for assessing edge freshness by contrasting a fresh wide edge with a three-week-old one, and explicitly mentions LIMITS (TTL, data gaps) that guide expectations. However, it does not explicitly state when not to use this tool versus alternatives like 'polymarket_edges', though the context makes it inferable.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it walks the order book ladder, returns a 'verdict' (clean/degraded/cannot_fill), and explains that thin books may strand the user unhedged. 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?

Despite being long, every sentence is justified. Information is front-loaded with purpose, then broken into clear sections (SINGLE-MARKET, BASKET). The usage warning is prominently placed. No unnecessary words; the length is appropriate 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?

No output schema, but the description enumerates all return fields for both modes: for single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). This makes the tool's behavior fully predictable.

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

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

Schema coverage is 100% but description adds significant meaning: it clarifies side default behavior per mode (auto for basket), interprets size_usd as 'spend on buys' vs 'target proceeds on sells' in single-market, and 'settlement notional' in basket. The explanation of default values and clamping range is additional value beyond the schema.

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

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

Description opens with a clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then splits into two distinct modes (single-market and basket), each with detailed purpose, and explicitly distinguishes itself from siblings by stating when to use it before other Polymarket 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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risk of partial basket fills converting an arb into an unhedged directional position, providing clear when-not conditions.

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

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

Adds significant context beyond annotations: explains the two modes, response structure (leg-by-leg prices, spread, top_spreads_pp), safety fields (compatibility_warning with two subcases, temporal_alignment, skipped counters). Discloses that real spreads are rarer than the shortcut list suggests. 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?

Efficiently structured: core purpose first, then modes, then response details, then safety fields. Each sentence adds unique information. Slightly long but justified given tool 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?

Comprehensive for a tool without output schema: covers response fields, modes, safety warnings, and temporal alignment. Lacks error handling for invalid parameters, but overall very thorough.

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

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

Schema covers all three parameters. Description adds meaning by listing the topic shortcuts and explaining the override behavior for explicit tickers. Provides examples and clarifies that topic auto-fetches events, which is beyond the schema's static 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?

Clearly states the verb 'Cross-venue spread' and the specific resources (Kalshi and Polymarket). Distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The description immediately conveys the value and scope.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers) and provides guidance on when each is appropriate. Warns that pre-mapped topics often return warnings, so agents know to expect limited tradeability. Could mention siblings like polymarket_arbitrage for within-venue analysis, but still very 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 (readOnlyHint, idempotentHint, etc.) already indicate safety; the description adds return format 'Returns matching rows as JSON' and details about SoQL clause formatting, which provides value beyond annotations.

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

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

Two sentences: first states purpose, second adds filtering details. Front-loaded and free of unnecessary words. Every sentence is valuable.

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 7-parameter tool with SoQL syntax, the description covers core usage, return format, and provides an example. It does not explain SoQL itself, but that is domain knowledge; overall sufficient.

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

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

Schema coverage is 100% but the description adds critical nuance: SoQL clauses must be without leading $, illustrated by an example. This enhances understanding beyond schema descriptions.

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

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

The description clearly states the verb 'Run', the resource 'Socrata SoQL query against a Oakland Open Data dataset', and the key parameter 'resource_id'. It distinguishes from sibling tools like 'datasets' which lists datasets, not query them.

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 lists filtering options (where, select, group, order, limit, offset) and clarifies SoQL syntax (no leading $). It implies usage for querying datasets, though it does not explicitly mention when not to use it or 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=true, idempotentHint=true, destructiveHint=false. The description adds context: it is scoped to the agent's identifier, and is used to retrieve stored data without side effects. No contradictions.

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

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

Three sentences, each adding essential information. No redundant words. The purpose is front-loaded, making it easy for an agent to understand quickly.

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 param, known schema), the description covers purpose, behavior, scoping, and relationships with sibling tools. No output schema exists, but the return behavior is implied. Completeness is high.

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 only parameter 'key' is already fully described in the schema (omitting lists all keys). The description restates this without adding new semantics. With 100% schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's core function: retrieving a saved value or listing all keys. It uses specific verbs ('retrieve', 'list') and distinguishes it from siblings like 'remember' and 'forget' by explaining the complementary pairings.

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

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

The description explicitly tells when to use this tool: 'look up context the agent stored earlier... without re-deriving it from scratch'. It also explains scoping and pairing with 'remember' and 'forget', but does not explicitly state when not to use it, leaving a minor gap.

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, destructiveHint. Description adds behavioral details: carries source, citation_uri, payload; explains mark_read side effect (flags read for next call); mentions polling is fine. No contradictions.

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

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

Three sentences, each packed with essential information: what returns, filtering, mark_read behavior, alternative endpoint. No redundancy or waste.

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

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

Given no output schema, the description adequately explains return fields (source, citation_uri, payload). Combined with annotation hints and full parameter schema, it provides complete context for an agent to use this 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 has 100% coverage with descriptions. Description adds value by providing example filter values (e.g., "sec_8k"), clarifying that since is an ISO timestamp, and explaining the side effect of mark_read. This goes beyond the schema.

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

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

Clearly states it pulls fired events from subscription feed and returns recent alerts. It specifies filtering by type and since, and mentions mark_read. Distinguishes from sibling tools like list_subscriptions by focusing on alert retrieval.

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

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

Gives clear context: polls work fine, alternative REST endpoint provided, and filtering options. Lacks explicit when not to use or comparison to siblings, but the context is sufficient for typical 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 readOnly, idempotent, and non-destructive behavior. The description adds rich detail: it fans out to SEC EDGAR, GDELT/GNews, USPTO; explains GDELT→GNews fallback; notes PatentsView API sunset soft-failure; and describes return structure (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is a single dense paragraph, front-loaded with example queries. It is efficient but could be slightly better structured with bullet points or clearer separation of source details. Overall, it is concise and informative, earning a 4.

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 structure (changes grouped by source, total_changes count, pipeworx:// citation URIs). It covers all sources, fallback logic, and parameter formats, providing a complete picture for a read-only query tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds extra context: for 'since', it explains ISO date vs relative shorthand with examples ('7d', '30d', '3m', '1y'); for 'value', it clarifies ticker or zero-padded CIK. This adds value beyond schema, earning a 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 explicitly states the tool provides a change feed for a company in the last N days/weeks/months, fanning out to multiple sources. It distinguishes from the sibling tool 'entity_profile' by specifying when to use that instead, making the purpose clear and unique.

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 example query phrases ('What's new with X', 'latest on Y') and explicitly contrasts with 'entity_profile' for static profile needs. It also explains fallback behavior (GDELT→GNews) and acceptable since formats, giving clear guidance on when and how 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?

Annotation idempotentHint=true suggests overwrite, but description doesn't confirm. Adds scoping and retention details 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?

Three efficient sentences front-loading purpose, then usage context and partner tools. No wasted words.

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

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

For a simple key-value store with no output schema, description covers purpose, when, scoping, persistence, and pairing — 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 has 100% coverage with examples. Description adds broader context on key-value usage (e.g., 'findings, addresses, preferences'), enhancing 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?

Clearly states the tool saves data for reuse across conversations/sessions. Distinguishes from siblings by explicitly naming recall and forget as partners.

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

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

Provides explicit when-to-use guidance with examples (resolved ticker, target address). Also covers persistence differences for authenticated vs. anonymous sessions.

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 significant behavioral details beyond annotations: unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully, and each call cascades through internal lookup endpoints. These enrich the readOnlyHint and idempotentHint annotations by describing fallback and error handling behavior, which is valuable for agent decision-making.

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

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

The description is thorough and well-structured with clear sections, but it is quite lengthy. The opening query examples are illustrative and useful, but some redundancy exists (e.g., repeating 'resolves to' multiple times). Overall it earns its length but could be slightly tightened.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior) and the absence of an output schema, the description covers all essential aspects: input formats, resolved outputs, unresolved handling, source citations, and graceful degradation. It is complete enough for an agent to understand what will happen and what to expect.

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

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

Although the schema already covers both parameters with 100% description coverage, the tool description adds significant semantic meaning: it explains value formats ('ticker (AAPL), CIK (0000320193), or name'), specifies what ISIN resolution entails, and clarifies the meaning of 'drug' and 'company' types. This goes well beyond the schema's brief 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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific examples and distinguishes the tool by noting it should be used 'FIRST whenever you have a name but need an ID.' The supported types are explicitly listed.

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

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

The description provides explicit usage context with 'Use FIRST whenever you have a name but need an ID' and numerous example queries. It does not explicitly state when not to use the tool or name alternative tools (like entity_profile), but the context of 'other tools require as input' implies the appropriate scenario, so clear exclusions are missing.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: it probes each entity using ai_visibility_check, ranks by score, and surfaces most/least recognized. 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 two sentences plus a brief clause, all front-loaded. Every sentence adds value: the first states the core action, the second explains the process and use case. No redundant information.

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

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

Despite lacking an output schema, the description explains the return format: ranked list with score, confidence, and signal density per entity. It also mentions the internal use of ai_visibility_check. It could briefly note constraints (e.g., entity count 2-8) or error conditions, but overall is sufficient for an agent to decide and invoke.

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 all 4 parameters. The description adds extra meaning: it notes that the first entity is treated as the 'subject' for narrative, and gives examples for 'context' (e.g., 'B2B SaaS'). This enhances understanding 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 a specific verb-resource pair: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison). The example 'does Claude know about us as well as our competitors?' clarifies the exact use case.

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

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

The description explicitly states it is 'Useful for competitive AI-marketing audits' and provides an example query. It implies use over ai_visibility_check when comparing multiple entities, but does not explicitly state when not to use or list alternatives. Minor improvement could include direct comparison to siblings.

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

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

Annotations already declare readonly, open-world, idempotent, and non-destructive. The description adds significant behavioral details: composite call structure, potential 5-30s delay for bundlephobia first measurement, and graceful degradation with sources_failed list.

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

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

The description is well-structured with a clear front-loaded purpose, but slightly verbose with details like the full field list and timing caveats. Could be tightened slightly without losing clarity.

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

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

Despite no output schema, the description fully enumerates the return value fields and explains partial failure behavior. All essential aspects are covered for an AI agent to understand what to expect.

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

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

Schema coverage is 100%, but the description adds meaningful context: explains that 'package' accepts scoped names like '@types/node', and that 'version' defaults to the latest published version when omitted. This clarifies default behavior beyond schema.

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

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

The description clearly states the tool performs a composite check for evaluating whether to add an npm package, combining data from deps.dev and bundlephobia. It specifies the exact output and distinguishes from sibling tools by noting ecosystem limitations.

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: when an agent asks about safety, popularity, size, or cost of adding a package. Also mentions when not to use (PyPI/Maven/etc. should use deps.dev directly) and handles partial failures gracefully.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and the description adds valuable behavioral details: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K chars), and output elements (offsets, similarity scores). No contradictions.

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

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

The description is concise and front-loaded with the core functionality. A second paragraph adds technical depth without redundancy. Some minor repetition could be trimmed, but overall well-structured.

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

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

Despite lacking an output schema, the description fully explains the return format (top-N passages with character offsets and similarity scores), embedding methodology, and integration with sibling tool ask_pipeworx_grounded, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameters with example queries for the 'query' parameter and explains the limit default, providing additional context beyond 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 identifies the tool as performing semantic search inside a fetched record, providing specific examples (SEC 10-K, article, long tool result) and distinguishing it from sibling tool 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?

The description states when to use the tool (when the record is too large for the prompt) and provides a usage pattern with ask_pipeworx_grounded. It lacks explicit 'when not to use' guidance but the context is clear.

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

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

The description discloses that the tool creates a subscription (non-readOnly), requires OAuth, and has constraints such as SMS verification and a 10/day cap. It also explains webhook signing and auto-disable after failures. Annotations are consistent (e.g., readOnlyHint=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?

The description is lengthy but well-structured: it starts with the core purpose, then details subscription types, then delivery channels. Every sentence adds value, though some users might prefer a more compact summary. The front-loaded first sentence is effective.

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

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

Given the tool's complexity (3 parameters with nested objects, 5 subscription types, delivery options) and no output schema, the description thoroughly covers all aspects: inputs, prerequisites, constraints, and return value (subscription id). It leaves no obvious gaps.

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

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

Although the schema already provides descriptions for all parameters, the description adds significant detail: it explains each subscription type's required/optional params (e.g., sec_8k items codes, polymarket_edge topics), delivery channel options, and constraints. This goes beyond the schema abstractions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to live-data event streams. It lists supported types (sec_8k, polymarket_edge, etc.) and distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 specifies that anonymous and BYO accounts cannot persist subscriptions, requiring a Pipeworx OAuth account. It provides when-to-use context for each subscription type and delivery channel, but does not explicitly mention alternatives like list_subscriptions or recent_alerts.

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, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it returns category-bucketed examples with tool+argument shapes. No contradictions, adds value beyond annotations.

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

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

Description is front-loaded with common queries but is somewhat lengthy. Could be more concise while retaining 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?

No output schema, but description explains return format (category-bucketed examples with tool calls). Adequate for a discovery tool with 1 optional param.

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 100%. Description explains the topic parameter with its focus areas and says 'omit for cross-category spread', adding meaning beyond schema.

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

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

The description clearly states it is the onboarding entry point, returning example questions. It distinguishes from sibling tools like ask_pipeworx by being the first-use discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and describes optional topic filtering. Lacks when-not-to-use but clear directive.

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

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

Discloses critical behaviors beyond annotations: ownership enforcement, deactivation rather than deletion, and data availability via recent_alerts. No contradiction with annotations (destructiveHint=false is consistent with non-deletion).

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

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

Two sentences, front-loaded with purpose, followed by ownership and behavioral details. No unnecessary words.

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

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

For a single-parameter, no-output-schema tool, the description covers purpose, ownership, id source, effect, and data retention. 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 provides 100% coverage with description of 'id'. The tool description adds context that the id is returned by subscribe, reinforcing the origin of the parameter.

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

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

Clearly states 'Cancel a subscription by id', using a specific verb and resource. Distinguishes from siblings 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing when-to-use and when-not-to-use guidance. Also clarifies the row is deactivated, not deleted, linking to recent_alerts.

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 rich behavioral context that annotations do not cover: it explains the meaning of 'could_not_verify' (system failure, not evidence) versus 'unsupported' (no source), reveals the internal routing logic (SEC EDGAR vs grounded pipeline), and notes the response includes a citation and reasoning. This goes well beyond the readOnly/openWorld/idempotent hints and provides critical guidance for interpreting 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 longer than a typical one-liner but every sentence contributes useful information: purpose, routing, return format, and critical caveats. It is well-structured, starting with the core purpose and then elaborating on behaviors. It is not excessively verbose for the tool's complexity, though it could be tightened by removing the call-count comparison ('Replaces 4–6 sequential calls') which is more of a benefit than a semantic 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?

The description covers all necessary aspects: what the tool does, how it routes different claim types, what it returns (verdict list, actual value, citation, reasoning), and how to interpret ambiguous outcomes ('could_not_verify' vs 'unsupported'). Although there is no output schema, the description explicitly lists the possible verdict values and the error field, providing sufficient completeness for an agent to invoke and handle 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% and both 'claim' and 'tolerance_pct' already have detailed descriptions in the input schema, including defaults and usage examples. The tool description does not add any additional parameter-specific meaning beyond what the schema provides (e.g., no extra detail on claim format or tolerance behavior beyond the schema's own text). Therefore, the description adds no incremental value for parameters, and a baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources,' with a specific verb ('verify') and resource ('claims'). It distinguishes itself from siblings by describing a fast path for company-financial claims and a grounded pipeline for other claims, which is more specific than general purpose tools like ask_pipeworx or 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear when-to-use directive. It also explains the routing behavior for different claim types and mentions it replaces 4–6 sequential calls, implying it should be used instead of chaining other tools. However, it does not explicitly name alternative tools or provide when-not-to-use conditions, so it doesn't fully meet the 'vs alternatives' bar.

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