Data Cityofchicago

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint as true. The description adds valuable behavioral context: default free model, BYO API key for Anthropic, per-model return structure, and combined view. 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, front-loaded with purpose and key details. Every sentence adds value; no redundancy.

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

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

Given 4 parameters, no output schema, and existing annotations, the description fully covers the tool's behavior, parameter roles, return structure, and use cases. No 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model, when to use _apiKey, and the purpose of 'context' for disambiguation.

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 clear verb-resource pair: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It distinguishes the tool from siblings like 'scan_competitor_ai_presence' and 'ask_pipeworx' by focusing on multi-model visibility scoring and return 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 explicitly gives use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use it or compare to alternatives, but the context is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context: it routes to the appropriate tool, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. This goes beyond the annotations, though it doesn't detail potential pitfalls or limitations (e.g., exact output structure), so a slight deduction from 5.

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

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

The description is longer than ideal but well-structured and front-loaded with the key directive. It uses examples and explicit alternative tool references efficiently. Every sentence contributes to usage guidance, though some repetition exists (e.g., 'START HERE' reinforces earlier points). Overall, it earns its length.

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

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

Given the tool's complexity (routing across thousands of sources), the description covers the input type, scope of data domains, output characteristics (structured with citations), and alternative tools. The absence of an output schema is compensated by the description's clarity on what is returned. The description is complete for an agent to decide when and how to invoke the 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 a clear description for 'question' and aliases documented. The tool description adds examples of well-formed questions, which implies the expected parameter format, but it doesn't add deeper semantic details beyond those examples. Given full schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it routes factual questions to one of 5,521 tools across verified sources and returns a structured answer with stable pipeworx:// citation URIs. It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, and explicitly labels itself as the default entry point.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' for a specific list of domains, trigger phrases like 'what is' or 'look up', and concrete examples. It also states when to step up to other tools ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'), covering both when-to-use and when-not-to-use.

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

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

The description goes beyond annotations by disclosing that this is a full working router, that it currently matches ask_pipeworx exactly, and that candidate routing improvements are only active when under test. It also notes that no candidate is currently active, providing useful real-time behavioral context. Annotations already indicate read-only, open-world, idempotent behavior, and the description does not contradict them.

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

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

The description is well-structured, starting with the core definition and then providing operational details. It is slightly verbose with some parenthetical and explanatory phrases, but each sentence adds meaningful context about beta status, current exact-match behavior, and comparison purposes. It earns 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?

Given no output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It also covers the router's scope, current candidate status, and experimental comparison purpose, making the tool's behavior sufficiently understandable for an agent selecting between this and the stable sibling.

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

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

The input schema has 100% coverage with clear descriptions for all parameters (question and its aliases). The description references the same arguments as ask_pipeworx but adds no additional semantic meaning beyond the schema, 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 identifies this as a beta version of ask_pipeworx with identical functionality (same router, same 5,521 tools, same arguments, same response shape), while distinguishing it as the experimental edge with candidate routing improvements. This is specific and differentiates it from the stable sibling tool.

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

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

The description provides explicit usage context: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It clearly explains the current status (no active candidate, so behavior matches ask_pipeworx exactly), but it does not explicitly state when NOT to use it in favor of the stable version, though the experimental nature implies caution.

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 discloses the internal routing across 5,521 tools/1452 sources, the constraint of extracting only from the tool result, and the full refusal_reason enum. It also reveals the extra LLM call overhead—valuable behavioral context not captured in annotations.

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

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

The description is dense but well-structured: it starts with the core purpose, then details the mechanism, output shape, refusal conditions, and usage guidance. Every sentence contributes unique, essential information 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?

With no output schema, the description fully specifies the success and refusal return objects, including fields and refusal reasons. Combined with clear use-case guidance and cost comparison, it makes the tool self-contained and actionable.

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

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

The input schema already provides complete descriptions for all 6 parameters (question plus 5 aliases) at 100% coverage. The description adds no additional parameter-level detail, so the baseline 3 applies.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a distinct focus on grounding answers in tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence extraction and explicit refusal behavior, making the purpose unambiguous.

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

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

Explicitly states when to use the tool: whenever an answer will be quoted, cited, or acted on, and facts must not be invented (e.g., financial verdicts, legal claims). It also names the alternative (ask_pipeworx) and recommends it for casual lookups, with a clear cost trade-off.

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 (readOnlyHint=true, openWorldHint=true, etc.) by detailing fan-out behavior, response shapes, resolution contract, parent event extraction, news fallback mechanisms, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. This level of detail provides comprehensive behavioral transparency with no contradiction to annotations.

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

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

The description is quite long and dense, containing many details that are valuable but could be streamlined or better structured. It front-loads purpose and usage, but later sections on response shapes, resolver contract, etc., while necessary, add length. A more concise presentation with clearer segmentation would improve scannability.

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

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

Given the tool's complexity (3 parameters, no output schema, many edge cases), the description is remarkably complete. It covers resolution confidence, parent events, news fallbacks, safety mechanisms, closed/dead markets, liquidity warnings, and cancellation risk. Every essential aspect for an AI agent to use the tool correctly is addressed.

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 all parameters. The description adds extra meaning: explains the market parameter accepts slug, URL, or question text; describes depth enum (quick vs thorough) and include_raw purpose. While the schema already covers basics, the description enriches understanding of parameter effects on tool behavior.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies accepted input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The verb 'research' and resource 'Polymarket bet' are specific, and the tool's focus is distinct from siblings like polymarket_arbitrage or polymarket_edges, though not explicitly contrasted.

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 provides usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly indicates when the tool should be used. However, it does not mention when not to use it or suggest alternative tools (e.g., polymarket_edges for purely edge detection), which would elevate the score.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds substantial detail: for type='company' it pulls specific financial metrics from SEC EDGAR/XBRL with correct off-calendar fiscal year handling; for type='drug' it pulls FAERS counts, FDA approvals, and trial counts. It also describes sorting by primary metric and output format (paired data + citation URIs). 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 front-loaded with example queries and gets straight to the point. Every sentence earns its place—example phrases, usage guidance, detailed data sources for both types, sorting behavior, and output format. It is appropriately sized for the complexity and has no filler.

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

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

No output schema is provided, but the description explains return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It covers both entity types thoroughly, mentions off-calendar fiscal year handling, and explains why this tool replaces many consecutive calls. The description is complete for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100%, but the description significantly adds meaning: it explains the two enum values ('company' pulls SEC data with fiscal year handling, 'drug' pulls FAERS/FDA/trial data) and clarifies the values array format (tickers/CIKs for company, drug names, 2-5 items). This goes well beyond the schema's short descriptions.

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

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

The description starts with clear example queries ('Compare X and Y', 'X vs Y') and explicitly states the tool does 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by noting it 'Replaces 8–15 sequential lookups' and is preferred over sequential 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?

The description gives strong guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explicitly tells when to use (comparing entities) and implies when not to use (single entity lookups). The alternative (sequential lookups) is mentioned as something to avoid.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no behavioral context beyond the implied 'search', such as pagination behavior or result format.

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 extremely minimal (3 words). While concise, it lacks sufficient detail, making it under-specified rather than appropriately compact.

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

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

With 3 undocumented parameters and no explanation of the dataset catalogue's scope or result structure, the description is inadequate for effective tool use, even though an output schema exists.

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 0%, meaning the schema provides no parameter descriptions. The description 'Search dataset catalogue' offers no clarification on the 'query', 'limit', or 'offset' parameters, leaving the agent without guidance on how to use them.

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 'Search dataset catalogue' clearly states the tool's verb and resource. However, it does not differentiate from sibling search tools like 'search_within' or 'deep_research', which may also search catalogues.

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 guidance on when to use this tool vs alternatives such as 'search_within' or 'query'. The description does not specify when not to use it or provide examples of appropriate use 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?

Despite having annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds rich behavioral detail: account and plan requirements, expected latency, gap recovery behavior, contradictions[] output, citation resolution semantics, and semantic excerpting. 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 substantive value. It is front-loaded with critical account requirements and a clear definition of what the tool does. While it could be tightened, the length is justified given the complexity of the tool and the need to prevent misuse.

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?

Considering the tool's complexity, the description covers all necessary context: account prerequisites, alternatives, result format, limitations, timing, and parameter effects. With no output schema, the description explains what the findings packet includes, making it fully self-contained for an agent to decide when and how to use it.

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

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

Schema already covers 100% of parameters with clear descriptions, but the description adds behavioral meaning to the depth parameter by explaining how each depth level affects hops and contradiction scanning. This goes beyond schema descriptions, providing deeper context for choosing 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 opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and explains the decomposition and parallel routing mechanism. It explicitly differentiates from the sibling ask_pipeworx by stating when to use each, making the purpose crystal clear.

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

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

Provides explicit when-to-use and when-not-to-use guidance: use ask_pipeworx for single lookups, for breaking/current news, or when not signed in. Also gives examples of ideal use cases ('compare X and Y's regulatory + financial exposure'). This is exemplary usage guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details beyond annotations: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 front-loaded with the core purpose and includes a list of use-case domains and output details. Every sentence contributes value, though slightly wordy. It could be more concise but remains well-structured and informative.

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 6 parameters, no output schema, and moderate complexity, the description adequately covers the tool's purpose, usage context, return format (names, descriptions, schemas, examples). It does not detail error handling or performance, but the information provided is sufficient for an agent to understand and invoke the tool.

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

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

Schema description coverage is 100% (all 6 parameters described in schema). The description provides examples of query values (e.g., 'look up FDA drug approvals') but does not add significant meaning beyond the schema definitions. Baseline 3 is appropriate as the description adds minimal extra semantics.

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

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

The description clearly states the tool finds tools by describing a data or task, with specific examples like SEC filings, drugs, etc. It distinguishes from sibling tools by explicitly stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This contrasts with direct query tools like 'query' or 'search_within'.

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 guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST ...'. It suggests this tool is for exploration before using other tools. However, it lacks explicit exclusion criteria or alternative tools for when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (false). The description adds context about parallel fan-out, soft-fail for patents, and output structure, which goes beyond annotations without contradiction.

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

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

The description is front-loaded with example queries and well-organized with bulleted output fields. Some redundancy exists but it remains efficient given the tool's complexity.

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

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

No output schema exists, but the description fully explains the return structure including CIK, filings, fundamentals, patents, news, and LEI. Limitations (patents sunset) and invocation details (parallel) are covered, making it complete for a holistic profile 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% and description adds essential context: type is only 'company', value accepts ticker or CIK, and names are not supported (with explicit workaround). This clarifies usage beyond the schema definitions.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company' with specific data sources (SEC, XBRL, USPTO, news, GLEIF) and output fields. It is clearly distinguishable from sibling tools like resolve_entity.

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 concrete example queries and explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also directs users to resolve_entity when only a name is available, giving clear when-to-use and when-not-to-use guidance.

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

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

Description adds context about clearing sensitive data and aligns with destructiveHint=true. No contradiction; annotations already declare destructive, description reinforces with use cases.

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

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

Two effective sentences with no wasted words, front-loaded with the main 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?

Simple tool with one parameter; description covers purpose, usage, and behavioral context completely.

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 description for the key parameter, so baseline. Description does not add extra semantics 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 verb 'Delete' and resource 'memory by key', and distinguishes from siblings by mentioning pairing with '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?

Explicitly tells when to use (stale context, task done, clear sensitive data) and suggests pairing with alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts specific elements, and outputs markdown, enhancing transparency beyond annotations.

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

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

The description is concise (3 sentences), well-structured, and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description fully explains the input, process, output format, 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 description coverage is 100%, so the baseline is 3. The description does not add information about parameters beyond what the schema already provides.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, detailing the process (fetch, extract, emit). It is distinct from sibling tools, none of which share this specific 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 explicitly lists three concrete use cases (client indexing, personal drafting, competitor auditing), providing clear guidance on when to use. It does not specify exclusions, but the context is sufficient.

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?

Disclosures beyond annotations: specifies scoping to caller's subscriptions, default active-only behavior, and lists return fields; no contradiction with annotations.

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

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

Two concise sentences: first states purpose and output, second gives usage context; front-loaded and 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?

Fully covers purpose, return format, and usage context for a simple list tool with one optional parameter and no output schema.

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

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

Schema coverage is 100%; description implies active-only default but does not expand on parameter beyond what schema provides; adequate but not exceptional.

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?

Explicitly states it lists the caller's active subscriptions and lists return fields, clearly distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides specific guidance: use to review current monitoring before adding more or to find an id to cancel; lacks explicit when-not-to-use but context is clear.

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

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

While annotations indicate a safe, read-only operation, the description adds no behavioral context beyond that. It does not explain what metadata entails or any side effects, but does not contradict annotations.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It lacks any useful structure or front-loading of 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 single required parameter and presence of an output schema, the description is wholly incomplete. It does not inform the agent about what the tool returns or how to effectively use it.

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 description does not mention the resource_id parameter or its purpose. With 0% schema description coverage, the description fails to add any meaning beyond the schema's minimal definition.

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 'Resource metadata.' is vague and lacks a verb. It does not specify whether the tool retrieves, updates, or performs another action. It provides minimal purpose clarity.

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 guidance is provided on when to use this tool versus alternatives such as query or entity_profile. The description offers no context for appropriate usage.

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

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

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint all false, the description carries full burden. It richly discloses behavior: returns a claim_token for unauthenticated filing, allows later lookup with that token, is rate-limited to 5 per identifier per day, is free, doesn't count against tool-call quota, and is read by the team daily with roadmap impact.

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?

Though longer than typical, every sentence earns its place: purpose, usage conditions, exclusions, token workflow, rate limits, and quota impact. Information is front-loaded with the core purpose first and logically flowed into usage, exclusions, token mechanics, and operational 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?

For a tool with 0 required params, nested context object, no output schema, and non-trivial behavior, the description is exceptionally complete. It covers what the tool does, when to use it, when not to, how to use claim_token for follow-up, rate limits, quota rules, and content guidelines, leaving no material 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?

Schema coverage is 100% with detailed descriptions for every parameter, so baseline is 3. The description adds significant value beyond schema: explains the claim_token round-trip workflow (file anonymously, then pass the token back later to read what changed), provides an example token format ('pwfb_…'), and gives message composition guidelines (be specific, 1-2 sentences, don't paste end-user's prompt).

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly states a specific verb, resource, and purpose. It enumerates concrete use cases (bug, feature/data_gap, praise) and implicitly distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on feedback rather than queries.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states exclusions: 'ONLY for tools served by this Pipeworx connection' and instructs to file with the correct server for other MCP connectors, including a way to identify Pipeworx tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII, only aggregated counts), and caching behavior (5min-1h). This goes beyond annotations to inform the agent about data freshness and ethical use.

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?

Every sentence earns its place. The description is front-loaded with the core output, then presents three bullet-point use cases, and ends with data source and caching notes. No redundancy; efficiently conveys all necessary information in minimal space.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It explains what is returned (top tools, top packs, call volume), the window options, caching, data source, and privacy. The agent can confidently select and invoke this tool based on this description alone.

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

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

The single parameter 'window' is fully described in the schema with its enum values and a brief description. The description goes further by explaining the semantic difference between short and long windows ('what's hot right now' vs 'steady-state demand'), adding meaning beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. This is a specific verb+resource combination (Returns + trending data) that distinguishes it from siblings like 'discover_tools' or 'ask_pipeworx' which serve different purposes.

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

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

The description lists three explicit use cases with bullet points, providing clear context for when to use the tool. While it doesn't explicitly state when NOT to use it or directly compare to siblings, the enumerated scenarios give strong guidance on appropriate usage.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral detail: scanning top 200 markets, Jaccard similarity anchor, partition filter with placeholder threshold, fill check with depth analysis. 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?

Description is lengthy but well-structured with clear sections for modes, filters, and response format. Every sentence adds value. Could be slightly more concise but appropriate for 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, so description compensates by fully explaining response fields (opportunities[], partition_check, fill_check) and edge cases like realizable_edge_pp ≤ 0. Covers all modes and parameters. Sibling reference for custom sizing.

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 context: event mode walks child markets, checks date-axis/threshold-axis ordering; topic mode searches related events, flattens markets. Provides example slugs and seed questions, going well beyond schema.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes from sibling tools like polymarket_edges by focusing specifically on arbitrage. Uses specific verbs and resources.

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

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

Provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Mentions when not to trade based on fill check. Lacks explicit exclusion of alternatives but strongly implies context.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: caching at KV level keyed on knobs, Fed bets excluded from ranking, diagnostics for empty segments, and details on model families and edge calculation. No contradiction with annotations.

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

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

The description is long but well-structured with section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded purpose. It could be slightly more concise, but every sentence adds value given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and caching. For a tool with 9 parameters and complex model logic, it is complete enough for an agent to understand selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema definitions by explaining the purpose of knobs like min_liquidity and max_spread_pp as 'tradeable-edge filters' and detailing how min_partition_leg_kelly differs from min_kelly, providing rationale for default 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb "Scan" and resource "top Polymarket markets" and distinguishes itself from siblings like polymarket_arbitrage by detailing its unique model-driven approach and edge calculations.

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 positions the tool for "what should I bet on today" scenarios and explains the tradeable-edge knobs for filtering. While it does not explicitly state when not to use it or compare to siblings, it provides clear context for when it is appropriate.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds significant detail: response structure (tracked, expired, snapshot_dates), data sources (daily closes, net of slippage), and constraints (TTL, snapshot gaps). 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 moderately long but well-structured: core purpose first, then args, response spec, and limits. Every sentence adds value. Slightly verbose but not wasteful.

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

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

Without an output schema, the description thoroughly explains the response format and edge cases (expired opportunities, snapshot gaps). It covers the tool's complexity fully.

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. The description adds context: 'lookback' for days, 'snapshot family' for window, and clarifies default/max values. This enriches understanding beyond the schema alone.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question of edge duration and trend. It distinguishes from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides context on when to use the tool (e.g., differentiating fresh vs old edges) and notes limitations (60-day TTL, daily closes). However, it does not explicitly advise against use in certain scenarios or compare to alternatives among 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 readOnlyHint, idempotentHint, etc. The description adds context: walks order book, returns specific fields like top_of_book, slippage, verdict, and explains forced_directional_risk. No contradiction. Adds significant 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?

Well-structured: overall purpose, then mode details with clear headings (SINGLE-MARKET, BASKET), then usage guidance. Slightly verbose but every sentence adds value. Front-loaded with purpose and requirement.

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

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

Without output schema, description fully covers return fields for both modes: top_of_book, vwap, slippage, shares_filled, max_fillable, verdict, theoretical_sum, realizable_sum, capture_ratio, profit, per-leg detail, thin_legs, max_clean_notional, forced_directional_risk. Completely addresses complexity of two modes and 4 parameters.

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 semantic meaning: side default and auto-detection in basket mode, size_usd interpretation differences (max spend vs target proceeds vs settlement notional). Goes 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 'Realizable-vs-theoretical edge check' and specifies two modes (single-market and basket), with verbs like 'walks the ladder' and 'returns'. It distinguishes from siblings by specifying it's a pre-trade risk check for arb signals and edge trades.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial basket fills cause directional risk). Also notes the requirement of one of market or event.

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?

Goes well beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing compatibility_warning triggers, temporal alignment conditions, and skipped cross types. 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Dense information without being overly verbose, though could be slightly more concise.

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 explains response fields (prices, spread, compatibility_warning, temporal_alignment). Covers limitations and failure modes. Lacks systematic return format but sufficient for understanding.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful context by explaining modes, how topic maps to events, and that explicit tickers override topic. Provides examples and clarifies the two operating 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?

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage. It specifies two modes (topic shortcuts and explicit tickers) and provides concrete examples.

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?

Explains two modes and conditions for meaningful spreads via compatibility_warning and temporal_alignment. Warns that pre-mapped topics may not be tradeable. Lacks explicit comparison to alternatives but provides sufficient context for appropriate use.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which characterize the tool as safe. The description adds no additional behavioral context (e.g., rate limits, pagination, or result format), so it provides minimal value 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?

At two words, the description is extremely concise, but it fails to convey essential information. It is under-specified rather than efficient, sacrificing clarity for brevity.

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 7 parameters, 0% schema coverage, and an output schema (not shown), the description is woefully incomplete. It does not state the tool's purpose, operation, or expectations for input/output, leaving the agent to infer everything from parameter names and examples.

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

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

Input schema has 0% description coverage for 7 parameters. The description 'SoQL query.' does not explain any parameter meaning, syntax, or expected values. Despite parameter names being somewhat self-explanatory, the agent receives no guidance on how to construct queries, especially for complex parameters like 'where' or 'select'.

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 'SoQL query.' adds minimal specificity beyond the tool name 'query'. It identifies the query language but does not state what the tool does (e.g., execute a query on a dataset and return results). This is slightly better than a tautology but still vague.

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 guidance is provided on when to use this tool versus alternatives (e.g., search, filter). There are no usage conditions, prerequisites, or exclusions, leaving the agent without decision context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; description adds scoping to identifier (IP, key hash, account ID) and the behavior of listing all keys when argument omitted. No contradictions.

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

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

Three concise sentences, front-loaded with main action. 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?

Covers key behaviors, scope, and relationships. Minor gap: does not describe return format or error handling, but overall sufficient for a simple retrieval 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 a single optional parameter; description adds context about omitting key to list all keys but doesn't significantly expand beyond the schema 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?

Clearly states the verb (retrieve/list) and the resource (values saved via remember). Distinguishes from sibling tools remember and forget.

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

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

Provides explicit use cases (look up target ticker, address, research notes) and mentions pairing with remember/forget. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, making the safe-read behavior clear. The description adds deeper transparency by explaining that mark_read:true flags events as read for subsequent calls, and that the same feed is accessible via an HTTP endpoint—both useful behavioral details not in 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?

Four sentences, each earning its place. The first sentence states the core purpose. Subsequent sentences explain return fields, filtering, mark_read behavior, and an alternative access method. No fluff, no repetition of schema or annotation fields.

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

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

Given the tool has 5 parameters, no output schema, and no nested objects, the description covers all essential aspects: what is returned, how to filter, how mark_read affects behavior, and even mentions polling suitability and an alternative HTTP endpoint. This is sufficient for an agent to invoke the tool correctly without additional context.

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

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

All 5 parameters have schema descriptions (100% coverage), but the tool description adds extra value: it explains the meaning of the returned fields (source, citation_uri), gives an example value for the type parameter ('sec_8k'), and clarifies the effect of mark_read. This goes beyond the schema's trivial descriptions like 'Optional — filter to one subscription type.'

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 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It explains the return fields (source, citation_uri, raw payload) and distinguishes the tool's scope from siblings by focusing on the subscription feed's persisted alerts.

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 filtering options (type, since, mark_read) and mentions polling works fine. Also notes an alternative endpoint (GET registry.pipeworx.io/alerts.json) for other use cases. Lacks explicit when-not-to-use guidance or direct sibling tool comparisons, but still offers practical usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context: it fans out to multiple APIs, has a GDELT→GNews fallback, soft-fails for USPTO due to sunset, and returns structured changes grouped by source. 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 concise and front-loaded with query examples, making it easy for an agent to grasp. Every sentence serves a purpose, and the structure is coherent.

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 input parameters, return structure (changes grouped by source, total_changes count, citation URIs), and source behavior. No output schema exists, but the description adequately describes the output format.

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 value by detailing the `since` parameter format (ISO date or relative shorthand like '7d', '30d') and explaining that `value` accepts ticker or CIK. Also clarifies that `type` only supports 'company' currently.

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 a change feed for a company over a time window, aggregating from SEC EDGAR, GDELT/GNews, and USPTO. It specifies the verb 'change feed' and distinguishes from the sibling 'entity_profile' tool.

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

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

The description explicitly tells when to use this tool (for recent changes) versus 'entity_profile' (for static profile), providing clear alternatives and exclusion criteria.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds valuable context about key-value scoping by identifier, persistence for authenticated users vs. 24-hour retention for anonymous sessions, and the ability to recall/forget. This goes beyond what annotations offer.

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 (4 sentences) and front-loaded with the main purpose. Every sentence adds value: purpose, usage guidance, storage mechanism, persistence rules, and tool pairings. No redundant or unnecessary text.

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

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

For a simple tool with full schema coverage and good annotations, the description is complete. It explains when to use, how storage works, and how to retrieve/delete. No output schema is needed as the tool is write-only. Minor: could mention overwrite behavior for duplicate keys, but 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?

The input schema covers both parameters with full descriptions (100% coverage). The description does not add new parameter-level meaning beyond the examples in the schema, but it provides behavioral context. Given high schema coverage, baseline 3 is appropriate.

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

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

The description clearly states that the tool saves data for later reuse, with specific examples (resolved ticker, target address, etc.) and distinguishes it from siblings like recall and forget. It uses a specific verb ('save') and resource ('data'), and explains the key-value pair scoping.

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 when to use ('when you discover something worth carrying forward') and when not to (avoid looking it up again). It also mentions pairing with recall and forget, providing guidance on alternatives. Authentication and session duration are clearly stated.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: it cascades through several lookup endpoints, returns specific fields (ticker, CIK, company_name, RxCUI, ingredient, brand) and citation URIs, and includes auto-disambiguation. 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 despite its length; every sentence adds value. It opens with concrete example queries, then states the tool's purpose, usage guidance, and supported types in a clearly structured format. No redundant or filler content.

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 lookup tool with no output schema, the description fully explains return values (ticker, CIK, RxCUI, ingredient, brand, citation URIs) and input handling. It even notes the internal cascading behavior. This is sufficient for an agent to anticipate results and side effects.

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

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

Schema coverage is 100%, but the description enriches both parameters: for 'type' it explains what each enum value returns, and for 'value' it gives input formats (ticker, CIK, name for company; brand/generic for drug) with examples (AAPL, 'ozempic'). This goes beyond the schema's simple descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with explicit examples like ticker, CIK, RxCUI. It distinguishes from siblings by framing it as the first step when you have a name but need an ID, and it details supported entity types and their specific outputs.

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: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, which helps the agent decide when to invoke it. The examples cover natural-language triggers and mention that other tools require these IDs, implying usage context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable context: it probes each entity using ai_visibility_check, ranks results, and treats the first entity as the subject. No contradiction with annotations.

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

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

Two concise sentences: first states core action, second provides usage context. No fluff, front-loaded, and every sentence adds value.

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

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

Despite no output schema, the description sufficiently explains return values (ranked list with score, confidence, signal density) and internal behavior (probes per entity with ai_visibility_check). Complete for an agent to understand.

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%. The description adds extra meaning beyond schema by explaining that the first entity in the entities array is treated as the subject for narrative, which is not described in the schema.

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

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

The description clearly states the verb 'Compare' and the resource 'AI visibility across multiple entities', and distinguishes it from siblings like ai_visibility_check and compare_entities by specifying side-by-side comparison and ranking.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and implies when to use this over single-entity checks, but does not explicitly state when not to use it or list alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds important behavioral details: fan-out across services, partial failures, bundlephobia delay (5-30s), and graceful degradation with sources_failed. This goes well beyond the annotations.

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

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

The description is slightly long (4 sentences) but front-loads the core purpose. Every sentence adds value, so no real waste. Could be a bit more terse but still 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?

For a complex multi-source tool, the description covers return fields, error handling, timing, and ecosystem limitations. No output schema, but description details the summary block and other return data.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds minor context (version defaults to latest) but does not significantly enhance semantic understanding.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, covering license, advisories, size, etc. It distinguishes itself by naming the services (deps.dev, bundlephobia) and ecosystem scope (npm only).

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

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

Explicitly says when to use: when asked if a package is safe/popular/small. Also specifies when not to use: for non-npm packages, directing to deps.dev:version directly. This provides clear guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds crucial behavioral details: backing embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and output details (passages with offsets and 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?

A single, efficient sentence covering purpose, context, output, and technical details. Every clause adds information with no redundancy. 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?

Given the absence of an output schema, the description thoroughly explains output (passages with offsets and scores), limitations (200K char cap), and related tools. It covers purpose, usage, and internal mechanics, making the tool well-understood without additional sources.

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

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

Schema already describes all 3 parameters (100% coverage). The description adds value by providing concrete examples for query ('supply-chain risk'), clarifying the default limit (5) and range (1-20), and giving context about what kind of text to pass (e.g., SEC 10-K body).

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

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

The description starts with 'Semantic search INSIDE a fetched record,' clearly stating the tool's unique function. It distinguishes itself from sibling tools by explaining it searches within a provided text, not a broader corpus, and mentions pairing with ask_pipeworx_grounded for grounding.

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

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

Explicitly advises use when 'the record is too big to cram into the prompt,' providing a clear context. It suggests a complementary workflow with ask_pipeworx_grounded but does not explicitly state when not to use this tool versus alternatives like ask_pipeworx.

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 behavioral traits beyond annotations: requires OAuth account, returns subscription id, explains type-specific parameters, details delivery channel behaviors (SMS verification, webhook signing, auto-disable). Annotations indicate idempotentHint=true but description doesn't address idempotency; however, it does not contradict annotations.

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

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

The description is a single paragraph that efficiently covers all necessary info with front-loaded purpose. It is somewhat lengthy but each sentence adds value; could benefit from bullet points but remains clear and 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?

The tool has 3 parameters with full schema coverage and no output schema, but the description covers prerequisites, type-specific filters, delivery options, and behavioral details (rate limits, verification, failure handling). It provides complete guidance for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, but the description adds significant meaning: for 'type', it explains each enum beyond label; for 'params', it provides detailed examples per type with specific keys; for 'delivery', it elaborates on channels, phone verification, email template, webhook signing secret, and auto-disable. This fully compensates with rich context.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create/resource) and distinguishes from sibling tools like list_subscriptions (list) and unsubscribe (delete).

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: requires Pipeworx OAuth account, lists supported subscription types with examples, and mentions delivery channels (feed, email, SMS, webhook) with constraints (SMS 10/day cap, webhook auto-disable). It does not explicitly compare to alternatives but indicates feed can be pulled via recent_alerts sibling, providing some guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns live-catalog examples and is an onboarding entry point, which complements annotations without contradiction.

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

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

The description is relatively long but well-structured, starting with the tool's intent, listing categories, and providing usage guidance. Each sentence adds value, though some redundancy exists with the title.

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

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

For a tool with one optional parameter and no output schema, the description fully explains its purpose, usage, and scenarios. It covers what the tool returns, how to use it, and when to apply it.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing possible topic values and explaining that omitting the parameter yields a cross-category spread, going beyond the schema's 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions. It distinguishes from sibling tools by specifying it is for learning what Pipeworx can do and how to call meta-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 FIRST when you do not yet know what Pipeworx can do for you' and explains the optional topic parameter. Lacks explicit when-not-to-use instructions but provides clear context.

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

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

The description adds significant behavioral context beyond annotations: it explains ownership enforcement (not in annotations), and clarifies that the operation deactivates rather than deletes (consistent with destructiveHint=false). This provides the agent with crucial behavioral information not available in annotations alone.

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 highly concise with three sentences covering action, constraint, and effect. Every sentence adds essential value with no redundant or filler content.

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

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

Given the simple input schema (one parameter) and no output schema, the description provides all necessary context: what the tool does, who can use it, and what the outcome is (deactivation, linking to 'recent_alerts'). It is complete for the tool's complexity level.

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% (the only parameter 'id' is fully described in schema). The tool description does not add new semantic meaning beyond what's already in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). The verb 'cancel' and title 'Unsubscribe from Alerts' specify the exact operation, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides usage context by noting ownership enforcement ('you can only cancel your own subscriptions') and the effect on data ('deactivated not deleted'). It implicitly guides against using this tool for other actions, but lacks explicit when-not-to-use or alternative tool references beyond mentioning '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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it uses two distinct pipelines (SEC EDGAR for financials, grounded pipeline for other claims), returns a verdict with evidence, and mentions it replaces 4-6 sequential calls. This provides transparency beyond the annotations without contradiction.

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

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

The description is moderately long but well-structured. It front-loads the purpose with examples, explains the two processing paths, describes the return format, and notes efficiency. Every sentence adds value, though it could slightly condense the examples 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?

Given the tool's complexity, the description covers key aspects: input types, processing paths, return values (verdict, value, citation, reasoning), and efficiency gains. However, it lacks details on error handling or edge cases (e.g., what happens if a claim is ambiguous), and the tolerance override behavior for non-financial claims is not fully explained.

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 value by explaining that tolerance_pct overrides the implied tolerance from the claim wording, with a default capped at 5, and provides examples for the claim parameter. This elaboration helps the agent understand parameter usage beyond the schema definitions.

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

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

The description clearly states the tool's purpose: verifying factual claims. It provides specific verb phrases like 'fact check,' 'verify the claim,' and distinguishes between company-financial claims and other claims with different processing paths. This is a specific verb+resource that differentiates it from all sibling tools, none of which offer claim verification.

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 when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It provides examples of claim types and how they are handled. However, it does not explicitly state when not to use the tool or mention alternatives, though no other sibling seems to perform claim verification.

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