Datos Gob Es

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that the default model is free, Anthropic requires the user's own API key, and the probe is non-destructive. It does not contradict annotations. Some details about rate limits or cost beyond BYO key are missing but not critical.

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 4 sentences, front-loaded with the tool's action and output, then details about models and return format. Every sentence adds necessary information without fluff.

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

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

Despite no output schema, the description explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters, use cases, and constraints. The tool is moderately complex with 4 params, and the description is fully adequate for an agent to use it 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?

With 100% schema description coverage, the description still adds value by explaining defaults ('Default model is Workers AI Llama-3.3-70b'), the purpose of _apiKey ('passed straight through to api.anthropic.com'), and context parameter use. This goes 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 specifies a clear action ('Probe one or more LLMs...score visibility') with a specific resource (entity), and the output format. It distinguishes this AI-visibility audit tool from sibling tools like ask_pipeworx and deep_research by focusing on LLM awareness scoring.

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

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

The description states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and model requirements. It does not explicitly say when not to use or contrast with alternative tools, but the purpose is sufficiently distinct.

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 beyond annotations (readOnlyHint, idempotentHint, destructiveHint): discloses it routes to thousands of tools, returns structured answers with citation URIs, and works on every tier in one fast call. No contradiction with annotations. Loses one point for not stating any potential limits like response size or timeout.

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

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

Description is detailed and front-loaded with the most important instruction. Some redundancy (e.g., listing many domain examples and then again in examples), but overall effective. Could trim a few phrases 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 (routes to 5,564 tools), the description provides sufficient context for an agent to decide when to invoke it. No output schema exists but the return value ('structured answer with citation URIs') is described adequately.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the single parameter accepts natural language and gives many example queries, but does not detail parameter formats or constraints beyond what schema shows. Slight credit for the guidance on question phrasing.

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

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

The description clearly states it is a routing tool for factual questions about current/historical data across many domains, with specific verb 'routes the question to the right one of 5,564 tools'. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by explaining when to use each alternative.

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 'PREFER OVER WEB SEARCH' and provides concrete when-to-use cues ('whenever the user asks what is, look up, find...') and when-not-to-use with named alternatives. Includes multiple examples illustrating appropriate queries.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining the fallback behavior (falls back to nothing, it's a full working router), the experimental nature, and the lifecycle context (candidate merged based on outcome evidence). The only gap is not explicitly stating what happens if the beta router fails (e.g., error handling), but given annotations cover core traits, this is adequate transparency.

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 distinction (beta version of ask_pipeworx) and then provides necessary context (identical nature, current state, usage guidance). It is concise with no wasted sentences, though it could be slightly tighter without losing meaning.

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 context (6 params, 100% schema coverage, no output schema, rich annotations), the description covers the essential experimental nature, current equivalence to stable, usage guidance, and fallback behavior. It is complete enough for an agent to understand when to select this tool and how to invoke it identically to the stable version.

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 documents all 6 parameters. The description adds no per-parameter details beyond what's in the schema, so credit is baseline 3. The description does not enhance understanding of parameter meaning or usage.

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 is an experimental version of ask_pipeworx with candidate routing improvements, explicitly distinguishing it from the stable sibling by noting it has the same tools, arguments, and response shape but operates as a testbed. This provides a specific action (ask via experimental router) and resource (beta router), making its distinct purpose unmistakable.

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

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

The description explicitly tells when to use this tool ('when you want the newest routing'), explains the current state (no active candidate, so it matches ask_pipeworx exactly), and hints at the alternative (stable router via sibling). This provides clear context for selection and exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it makes an extra LLM call, returns a structured response with explicit refusal reasons, and extracts only from the tool result. 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 well-structured with the main purpose front-loaded. It uses a list for refusal reasons, and every sentence adds value without redundancy. It is appropriately sized for the complexity of the tool.

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 (refusal modes, multiple aliases, cost trade-off, no output schema), the description is thorough. It explains the return format, refusal reasons, and when to use. No output schema exists, so the description fully covers the return value semantics.

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 merely lists aliases and states 'Your question in natural language,' which adds minimal meaning beyond the schema. The schema already describes each alias, so the description does not compensate further.

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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by noting the extra cost and different use case, making the purpose unambiguous.

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

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

The description provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off, giving clear when-to-use and when-not-to-use instructions.

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?

Exceedingly transparent beyond annotations: explains parallel fan-out, response shapes, resolver contract with confidence levels, parent event extraction, news fallback fields, safety short-circuiting for low-confidence/closed markets, wide-spread warnings, and cancellation rule parsing. 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 (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with main purpose. However, length is excessive; while each part adds value, it could be shortened without losing critical information.

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

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

Given no output schema, description fully covers return values: market fields, analysis, evidence, resolver contract, parent events, news fields, safety behaviors, wide-spread handling, and cancellation rules. Addresses edge cases and blocking paths comprehensively.

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

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

Schema covers all 3 parameters with descriptions, but description adds substantial meaning: explains how depth controls fan-out extent, when to use include_raw, and examples for market parameter. Provides context far beyond 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?

Clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. Specifies multiple input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Distinct from sibling tools like polymarket_edges or polymarket_arbitrage which are more specialized.

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 lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Covers safety mechanisms and resolution-rule risks. However, does not explicitly mention when not to use it or provide direct comparisons to sibling tools.

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

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

The description adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. Annotations already indicate read-only, idempotent, non-destructive behavior, which the description aligns with.

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

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

The description is well-structured with example queries front-loaded. It conveys necessary information without superfluous text. Slight room for improvement in organization (e.g., separating type behaviors more clearly), but overall 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?

For a tool with two entity types and no output schema, the description covers all essential aspects: entity-specific behavior, data sources, sorting, output format (paired data + URIs), and efficiency rationale. It is complete given the complexity and structured fields.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds practical context: explains what type='company' vs 'drug' pulls, and clarifies values format (tickers/CIKs for company, drug names). This adds meaning beyond the schema's enum and basic descriptions, but the schema already covers the essentials well.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, using specific trigger phrases. It distinguishes from siblings like entity_profile by highlighting efficiency.

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

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

Explicitly instructs to always prefer this tool over sequential single-entity lookups when comparing. Provides clear context for when to use it (comparison queries like 'X vs Y', 'rank these companies').

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it returns specific fields (title, description, publisher, etc.) and the origin (datos.gob.es), but does not disclose additional behavioral traits like authentication or rate limits. Since annotations cover safety, a score of 3 is appropriate.

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 sentence that is well-structured and front-loaded with the verb and resource. Every part adds value without extra words.

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

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

For a simple single-fetch tool with 1 parameter, annotations, and an output schema, the description adequately explains what it does and what it returns. It covers the necessary information but could mention error handling or authentication briefly.

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%, so the description bears the burden of explaining the 'id' parameter. It only says 'by its ID' and provides no details on format, examples (though schema has an example), or constraints. This is insufficient for low coverage.

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 'Fetch' and the resource 'full metadata for a single datos.gob.es dataset by its ID'. It also lists specific returned fields, distinguishing it from sibling tools like 'datasets' which likely return lists.

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

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

The description implies use when you have a dataset ID and need full metadata, but does not explicitly state when not to use it or compare with sibling tools such as 'datasets', 'themes', or 'publishers'. No exclusions mentioned.

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

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

Annotations provide safety and idempotency info (readOnlyHint, idempotentHint, destructiveHint false). The description adds the behavior of paginated listings and the specific portal, which is sufficient 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?

Single sentence, efficiently front-loaded with the action verb 'Search', no filler. Every part adds value.

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

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

Given the output schema exists to document return values, the description covers the essential behavioral aspects (search, pagination, portal, fields). Annotations cover safety. No major 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?

The schema has 0% description coverage, so the description must compensate. It mentions 'keyword, theme, or both' but does not explicitly map parameters (e.g., query=keyword, theme=theme) or explain page/page_size. The examples help, but explicit guidance is missing.

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 searches the Spanish open data portal by keyword, theme, or both, and specifies the return fields (title, publisher, download links). It distinguishes from sibling tools like 'dataset' (singular) and 'themes'.

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

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

The description implies usage for searching open data by keyword/theme but does not explicitly state when not to use it or mention alternatives. Given the sibling list, no other tool directly competes, so the context is clear enough.

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 (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral detail: account requirement, parallel decomposition, depth-level specifics (quick=3 facets, standard=gap recovery, thorough=leads), return format with verbatim evidence, confidence, source, gaps[], contradictions[], hop field, citation_uri, semantic excerpting, and expected latency (15-60s, up to 90s). No contradictions with annotations; openWorldHint aligns with access to external structured sources.

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

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

Despite being long, the description is efficiently structured: it leads with the critical account requirement and alternative tool, then explains the core mechanism, use cases, depth differentiation, and return details. Every sentence serves a purpose, and information is front-loaded for quick understanding. 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 the tool's complexity (2 params, no output schema, three depth levels, parallel execution), the description covers all essential aspects: purpose, usage context, prerequisites, behavioral nuances, parameter meanings, return format, limitations (breaking news gaps), alternatives, and performance expectations. Nothing critical is omitted.

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?

Both parameters (question and depth) are fully described in the input schema (100% coverage). The description adds meaningful context: natural language question examples, how depth levels differ in facets and hops, and the effect of each depth on gap recovery and contradictions. This exceeds baseline 3 by clarifying the enum behavior in practice.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and returns a 'findings packet' with evidence and citations. It distinguishes itself from siblings like ask_pipeworx (single lookup) and explicitly says it is not open-web search, making its purpose specific and unambiguous.

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

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

The description provides explicit guidance on when to use the tool ('broad/multi-part questions over structured data') and when not to (breaking news, single lookup). It names the alternative ask_pipeworx for those cases and even notes account requirements and depth tier differences, making the decision context very clear.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds behavioral context: returns top-N most relevant tools with full schemas and curated examples, ready to call directly without second lookup. 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 front-loaded with the core purpose, followed by use cases and details. Efficiently conveys comprehensive information without redundancy, though slightly verbose in listing domains.

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

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

Despite lacking an output schema, the description fully explains return contents (names, descriptions, schemas with examples) and usage context. Adequate for a simple discovery tool with one required parameter.

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 all 6 parameters. Description adds value by explicitly listing aliases (task, q, description, search) and clarifying the query parameter's nature (natural language). Includes examples in schema.

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

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

Description clearly states the tool finds tools by describing data/task, lists many domains, and distinguishes from siblings by positioning it as the first call for discovery ('Call this FIRST'). Specific verb+resource with extensive 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?

Explicitly states when to use: when you need to browse, search, look up, discover tools. Provides context ('Call this FIRST when you have many tools'). Lacks explicit when-not-to-use scenarios, but the purpose 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. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields, and mentions that patents soft-fail. 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 fairly long but well-structured with example queries at the beginning, followed by usage guidance and a detailed list of return fields. Every sentence adds value, though it could be slightly more concise by using bullet points.

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 what the tool returns: cik, recent_filings with URIs, fundamentals from 10-K, patents (with caveat), news via GDELT/GNews, and LEI. It covers limitations and input constraints, making it complete for a complex tool.

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

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

Both parameters are fully described in the schema (100% coverage). The description enhances by explaining that 'type' is limited to 'company' and provides detailed guidance on 'value' (ticker or zero-padded CIK), explicitly stating that names are not supported. This adds significant meaning beyond the schema.

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

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

The description uses a specific verb phrase ('full cross-source profile of a US public company') and provides multiple example queries that clarify the tool's purpose. It explicitly distinguishes itself from chaining multiple single-source lookups, making it clear what this tool uniquely offers.

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

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

The description explicitly states when to use this tool ('when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first'). It also notes limitations (patent API sunset) and provides clear input formatting instructions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms deletion and adds context about clearing sensitive data, but does not introduce new behavioral traits beyond annotations.

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

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

Two concise sentences: first states purpose, second gives usage context. No fluff, front-loaded.

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

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

For a simple tool with one required parameter, annotations, and no output schema, the description fully covers purpose, usage, and sibling relationships.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete'. Description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and explicitly distinguishes from sibling tools 'remember' and 'recall' by pairing with them.

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

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

Provides explicit when-to-use guidelines: 'when context is stale, the task is done, or you want to clear sensitive data', and mentions pairing with sibling tools, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds process details (fetches page, extracts title/description/key links, emits markdown) and output format, which go beyond annotations.

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

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

Two tight sentences plus a bullet list of use cases. Front-loaded with purpose. Every sentence adds value with no redundancy.

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

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

For a simple tool with two params and no output schema, the description fully explains the behavior, output format, and use cases. No missing crucial information.

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

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

Schema covers 100% of parameters with descriptions. The tool description does not add new information about parameters beyond implying the URL is used for fetching. Lacks details on max_links default/range already in schema.

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

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

Description clearly states verb (generate), resource (llms.txt file), and distinguishes from all sibling tools. It specifies the exact output format and the process.

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?

Description provides explicit use cases (client's site, own project, competitor audit). It doesn't include when-not-to-use but the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by specifying return fields and caller scope, exceeding baseline expectations.

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 the main action, no wasted words.

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

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

No output schema, but description lists all return fields. Provides usage context. Fully adequate for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra semantics for the include_inactive parameter beyond what schema provides.

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

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

The description clearly states the verb (List), the resource (the caller's active subscriptions), and explicitly lists the fields returned. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly suggests when to use (before subscribing or to get cancellation IDs) but does not state when not to use it. Still 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?

Annotations are all false (no hints), so the description carries the full burden and delivers rich behavioral context: rate limiting (5/day), free usage, claim_token return flow, and the fact that it does not consume quota. It also clarifies that filing without an account returns a token, and that passing it later reads resolution status. 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 well-structured with a clear logical flow: purpose, use cases, scope limitation, claim-token behavior, and operational notes. Every sentence adds value, though it could be tightened in places. Slightly verbose but earns its length for a nuanced tool.

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

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

For a tool with 4 parameters, 0 required, nested objects, and no output schema, the description covers all essential aspects: why to use it, scope restrictions, account-free claim behavior, rate limits, and what happens after filing. It even explains the output (claim_token and later status) without a formal output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains how claim_token is used in subsequent calls, and ties the 'type' field to real scenarios. It doesn't repeat schema descriptions word-for-word but augments the overall usage model.

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: telling the Pipeworx team about broken/missing/wanted functionality. It explicitly names the verb ('tell') and the resource (Pipeworx team), and distinguishes itself from sibling tools by focusing on feedback rather than querying, searching, or acting.

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

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

Provides explicit when-to-use guidance with concrete examples (bug, feature/data_gap, praise) and a clear exclusion: only for tools served by this Pipeworx connection, not other MCP servers. Also explains the claim_token workflow and rate limit, giving the agent situational context.

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

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

Adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). Annotations already indicate read-only, idempotent, non-destructive; description supplements well.

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

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

Concise single paragraph with bullet-like use cases, no redundancy. Front-loaded with purpose and scope.

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 simple input and no output schema, description provides all necessary context: return contents, use cases, caching, data source. Complete for a read-only trending 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 covers window parameter with enum and description. Description adds practical insight: shorter windows show hot trends, longer windows show steady-state demand.

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

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

Clearly states it returns trending tools/packs and call volume over time windows. Differentiates from siblings which are for other tasks like asking questions or deep research.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, checking alignment). Does not mention when not to use, but context is clear.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds extensive behavioral details: monotonicity checks, partition_sum logic, Jaccard similarity threshold, placeholder filtering, CLOB depth validation. Contradicts nothing.

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. While somewhat lengthy, every sentence adds value. Could be slightly more concise, but effective.

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

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

Despite no output schema, the description details the response format (opportunities[], partition_check, fill_check) and key edge cases (placeholder filtering, similarity threshold). Comprehensive for a complex financial 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 covers 100% of parameters with descriptions. Description enhances this with usage hints (recommended mode, examples, acceptance of full URLs), providing practical guidance 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 defines the tool as finding arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes: trending scan (no args), single-event (event), and cross-event (topic), each with specific behavior.

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 recommends event mode for specific markets and explains when to use topic mode. Describes the fill check to avoid trading when edge is unrealizable. However, does not compare with sibling tools like polymarket_edges or polymarket_edge_tracker.

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, open-world, idempotent, non-destructive behavior. The description adds extensive context: caching (1h), internal mechanisms (model families, gates), diagnostic output, and edge calculation details. 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 verbose but well-structured with segments and bullet points. Every sentence adds detail. For a complex tool, the length is justified, though slightly less concise than ideal.

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

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

Given 9 optional parameters and no output schema, the description thoroughly covers the response structure (segments, diagnostics, field descriptions), caching policy, and edge 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?

All 9 parameters have schema descriptions (100% coverage). The description adds value by explaining parameter interactions (e.g., min_kelly vs min_partition_leg_kelly) and usage context 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the use case ('what should I bet on today') and distinguishes from siblings by detailing its unique segments and algorithms.

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 targets discovery without paging hundreds of markets and explains when to use each segment. It lacks direct 'when not to use' or explicit alternatives, but the context is sufficient for appropriate 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=true and idempotentHint=true, indicating safety. The description adds significant behavioral context beyond annotations: it details the computation of trend, first_seen, decay, expired opportunities, snapshot dates, and limitations (60-day TTL, daily closes). It also explains the signed nature of edge_pp_net. 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 the main purpose in the first sentence, uses technical jargon efficiently, and each sentence adds value. It is concise given the complexity of the tool, with no wasted words.

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

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

The tool has no output schema, but the description compensates by thoroughly explaining the response structure (tracked[], expired[], snapshot_dates[]) with detailed field explanations. It covers limitations, data sources, and computational details, making the tool's behavior fully understandable for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides default values and clamp ranges for 'days' and 'window' that are also present in the schema. It adds minor context (e.g., 'snapshot family' for window) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states that the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs (tracker/telemetry) and resource (snapshots), and distinguishes the tool's purpose with an analogy about fresh vs. old edges, effectively differentiating it from related tools.

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

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

The description explains that the tool is used to analyze edge persistence over time, but does not explicitly state when to use it versus alternatives or when not to use it. Context about sibling tools is available but not referenced, leaving usage boundaries implied rather than explicit.

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

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

Annotations (readOnlyHint, idempotentHint, non-destructive) are consistent with a read-only check. The description adds rich behavioral details: it walks the order ladder, returns verdict (clean|degraded|cannot_fill), identifies thin legs and forced directional risk, and explains return values like vwap_fill_price, slippage_pp, and profit_usd, going far beyond annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, and front-loads the purpose. However, it is slightly verbose with explanatory phrases like 'the dominant loss mode in real arb-bot P&L,' which could be trimmed. Still, it remains efficient given the complexity.

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

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

Despite no output schema, the description exhaustively lists expected return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, max_fillable_usd, theoretical_sum, capture_ratio, etc.). It covers parameter requirements, defaults, and edge cases (thin legs, forced directional risk), making it fully actionable for an AI agent.

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

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

Schema coverage is 100%, but the description enriches every parameter: it explains size_usd differently for single-market (max spend vs target proceeds) and basket (settlement notional), clarifies default for side in basket mode (auto), and distinguishes between market and event parameters. This adds significant value beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly relates it to sibling tools like polymarket_arbitrage and polymarket_edges, making its purpose unambiguous.

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

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

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about partial basket fills converting arb into directional positions, providing clear contextual guidance.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds significant value by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining when spreads are meaningful versus when they are not. 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 thorough and well-structured with sections (modes, response, safety fields). While somewhat lengthy, every sentence adds unique value. Could be slightly more concise without losing information.

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

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

Given the tool's complexity (two modes, multiple safety fields, no output schema), the description is highly complete. It explains response structure, compatibility warnings, temporal alignment, and skip counters, enabling the agent to fully understand tool behavior and interpretation of results.

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

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

Schema provides full descriptions for all 3 parameters (100% coverage). The description adds extra context: enumerates the 10 topic shortcuts, explains how explicit parameters override topic mappings, and details response fields. Exceeds baseline 3.

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

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

The description clearly defines the tool as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes it from sibling tools like polymarket_arbitrage by specifying it computes spreads across two different prediction markets.

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

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

Explicitly describes two usage modes: topic shortcuts and explicit event pairing. Provides guidance on when each mode is appropriate and warns that most pre-mapped topics return compatibility_warning, helping the agent set expectations and choose 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?

Adds useful context beyond annotations: limits results to 50, returns specific fields. Annotations already indicate safe read, and description aligns with 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?

Single, front-loaded sentence with no wasted words; efficiently conveys purpose, scope, and constraints.

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 purpose, output fields, and limit. With an output schema present, doesn't need to detail returns further. Minor omission: limit parameter optionality not stated.

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

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

Description implicitly explains the 'limit' parameter by stating 'up to 50 results', adding meaning beyond the schema's bare type. With 0% schema coverage, this compensates well.

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

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

Clearly states verb 'List', resource 'public-sector publishers', specific source 'datos.gob.es', and output details (names, IDs, up to 50 results). Distinguishes from siblings as no other tool lists publishers.

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?

Implied usage for listing publishers from Spanish open data portal, but lacks explicit guidance on when to use or not use, and no alternatives mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds context about scoping and pairing, which is helpful but not essential 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 extremely concise—two sentences—with all essential information front-loaded. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully explains its behavior, scoping, and integration with sibling tools. 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?

The schema covers the single 'key' parameter 100%, but the description adds the critical nuance that omitting the key lists all saved keys—a behavior not evident from 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 uses specific verbs 'Retrieve' and 'list' to clearly state the tool's purpose: getting a saved value by key or enumerating all keys. It 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?

The description explicitly says when to use this tool—to look up context stored earlier—and mentions it pairs with 'remember' and 'forget'. However, it does not explicitly state when not to use it or contrast with other tools like 'search_within'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds value by explaining the feed persistence, mark_read effect on subsequent calls, and the link to an external GET endpoint. 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?

Four sentences, each serving a distinct purpose: core function, returned fields, filtering, and practical notes. No redundancy or filler. Information is front-loaded.

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

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

Lacks output schema but description adequately covers return format (source, citation_uri, raw payload). Addresses limit behavior implicitly via schema. Provides enough context for a feed-polling 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% with each parameter documented. Description adds usage context for type, since, and mark_read but does not mention unread_only. Overall, the schema already carries the bulk of parameter meaning, so description provides marginal extra value.

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

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

Clearly states the tool pulls fired events from a subscription feed and describes what each alert carries (source, citation_uri, raw payload). Provides specific verb+resource and enough detail to distinguish from siblings like list_subscriptions.

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

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

Explicitly mentions filtering by type and/or ISO timestamp, and the mark_read flag for controlling read state. Notes that polling works and an alternative GET endpoint exists for scripts/dashboards. Lacks explicit when-not-to-use or comparison with siblings but offers solid context.

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

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

Adds detailed behavior (fans out to three sources, fallback, soft-fail for PatentsView, return structure) beyond annotations which already indicate read-only, open-world, idempotent, non-destructive.

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

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

A single, dense paragraph front-loaded with query examples. Every sentence adds value; no redundant information.

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

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

Given tool complexity (multiple sources, fallback, no output schema), the description fully covers behavior, parameters, and return format (grouped changes, total count, citation URIs).

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 3 parameters are described in schema (100% coverage). The description adds context: relative shorthand for 'since', typical usage suggestion, and explanation of 'value' accepting ticker or CIK.

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

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

The description clearly states it provides a change feed for a company over a recent window, with example queries and explicit differentiation from entity_profile for static profiles.

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

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

Explicitly tells when to use this tool vs entity_profile, and describes fallback behavior between GDELT and GNews.

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

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

Beyond annotations (idempotentHint true, destructiveHint false), the description adds critical context: memory is key-value and scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. It also mentions pairing with recall/forget, which informs the agent about lifecycle.

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 with no waste. First sentence states purpose and scope. Second gives usage trigger. Third covers behavioral details and pairs with siblings. Front-loaded correctly.

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 is complete. It fully explains purpose, usage, behavior, and relationships to sibling tools. 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?

Input schema covers 100% of parameters with descriptions. The description adds examples (e.g., 'subject_property') but does not significantly enhance meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action (save), resource (data), and scope (across conversations/sessions). It also distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward' and 'so you don't have to look it up again'. It also mentions scoping by identifier and persistence differences for authenticated vs. anonymous users. No 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial context: internal cascading of lookups, graceful degradation if GLEIF/OpenFIGI unavailable, explicit `unresolved` handling, and source labeling. This exceeds baseline by disclosing behavior 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 longer than average but well-structured: starts with user queries, states purpose, then details supported types and behavior. It is dense but every sentence adds value. Slight over-verbosity in the middle section prevents a 5.

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 resolution tool with no output schema, the description covers input variants, output identifiers, fallback behavior, unresolved handling, and internal cascade. It is highly complete for the tool's complexity and fully prepares the agent to use it appropriately.

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

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

Schema coverage is 100% with good parameter descriptions, but the description enriches meaning further by detailing accepted input formats (ticker, CIK, ISIN, name for company; brand/generic for drug), giving examples, and explaining ISIN-to-LEI mapping. This goes beyond the schema's baseline.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers. It gives example queries and explicitly says 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools that consume IDs or profiles.

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

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

Provides explicit usage guidance with example queries and the directive 'Use FIRST whenever you have a name but need an ID.' The context of 'other tools require as input' indicates it is a prerequisite, and it mentions it replaces 2-3 manual lookups, clarifying 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds behavioral context: it probes each entity with ai_visibility_check, treats the first entity as the 'subject' for narrative, and returns a ranked list. No contradiction.

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

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

The description is three sentences: first states purpose, second explains mechanism, third gives use case. It is front-loaded and free of redundant information.

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

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

Despite no output schema, the description specifies the return format: ranked list with score, confidence, and signal density per entity. It also explains the dependency on ai_visibility_check. The tool is simple and the description covers all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in the entities array is treated as the 'subject' for narrative, while the rest are competitors, which is not in 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?

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly identifies the use case: competitive AI-marketing audits. It implies that for single entity checks, ai_visibility_check should be used. It could be more explicit about when not to use this tool, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds: fans out across two services, partial failures degrade gracefully, Bundlephobia first measurement can take 5-30s, sources_failed field lists failures. 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?

Purpose is front-loaded. Single paragraph, but every sentence adds value, covering usage, behavior, and output. Could be slightly more concise but overall efficient.

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

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

With no output schema, description thoroughly details return structure: summary block fields, per-advisory detail, links, alternative versions. Also covers partial failure and sources_failed. Very complete given the complexity.

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

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

Schema covers both parameters fully. Description adds useful clarifications: scoped packages are accepted, version defaults to latest when omitted, going 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?

Description clearly states the tool as a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying that other ecosystems are handled elsewhere.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, or size. Also guides when not to use by noting PyPI/Maven/Cargo/Go should use deps.dev:version directly.

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

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

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. Annotations already indicate safety and idempotency, and description adds substantive behavioral context.

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

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

Concise (~150 words), front-loaded with core purpose, then usage guidance, then technical details. No redundant sentences; all information earns its place.

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

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

No output schema, but description explains return format (passages with offsets and scores) and internal mechanics. Lacks explicit output field names but sufficient for agent understanding.

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

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

Schema coverage is 100% with descriptions, but description adds value with concrete examples (SEC filing, article, query examples) and clarifies default limit. Enhances understanding beyond schema alone.

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

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

Description clearly states the tool performs semantic search inside a provided text, returning relevant passages with offsets and scores. It distinguishes from siblings by specifying it operates on fetched records and pairs with ask_pipeworx_grounded.

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

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

Explicitly advises when to use (record too large for prompt) and provides an alternative (ask_pipeworx_grounded for grounding). Implies proper context 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 indicate idempotentHint=true and destructiveHint=false. The description confirms it creates a subscription (write operation) and returns an ID. It mentions OAuth requirement, delivery limits, and webhook signing secret, adding transparency beyond annotations. No contradiction.

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

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

The description is a single paragraph but packs substantial information efficiently. It front-loads the core purpose and then details types and delivery. Some structuring (lists or bullets) could improve readability, but it remains 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?

Despite no output schema, the description states it returns a subscription ID, which is sufficient for a create tool. All 3 parameters are thoroughly covered, including nested delivery fields. The tool's side effects (subscription creation, webhook secret returned once) are clear.

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

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

Schema coverage is 100%, and the description adds detailed semantics for each parameter: type enum with examples, params with type-specific structures, and delivery with constraints and examples for email, SMS, and webhook. This adds significant value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It lists specific event types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It explains type-specific parameters and delivery constraints (phone verification, 10 SMS/day cap). Although it doesn't explicitly say when not to use, the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds meaningful behavioral context: it draws from a live catalog, returns example questions and tool shapes, and is the first tool to use. No contradictions. Could mention response size or limitations but not necessary given annotations.

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

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

The description is well-structured, front-loading the purpose with common user questions. It is informative but slightly long; however, every sentence adds unique value. Minor redundancy in listing categories could be trimmed, but overall 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?

The description is comprehensive for a discovery tool with no output schema. It explains the return format (category-bucketed examples with tool shapes), how to use the tool (with/without topic), and when to use it (first contact). It also mentions meta-tools, covering all contextual needs.

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

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

Schema coverage is 100% and the description significantly adds value beyond the schema. It explains the categories, that omitting topic gives a full spread, and provides example values. The description enriches understanding of the 'topic' parameter.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions with tool shapes. It effectively distinguishes from siblings by emphasizing 'use this FIRST' and provides specific use cases (e.g., 'what can I ask Pipeworx?'). The verb 'suggest_questions' matches the description.

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

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

The description explicitly says to use this tool first when unfamiliar with Pipeworx or to learn meta-tool calls. It explains when to call with or without the 'topic' argument. However, it does not compare with specific sibling tools or state exclusions, which would make it a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns labels and IDs for filtering, which is useful but not extensive. It does not discuss pagination or rate limits.

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

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

The description is a single sentence that is front-loaded with the action and resource, containing no wasted words. It efficiently conveys purpose, examples, and usage context.

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

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

Given the tool's simplicity (one optional parameter, output schema present, strong annotations), the description covers the main points: what it does, where it applies (datos.gob.es), and its role as a filter. Missing parameter guidance is a minor gap.

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 0% description coverage for its only parameter 'limit'. The description does not mention or clarify the 'limit' parameter at all, leaving the agent without guidance on its meaning or usage.

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 'List' and the resource 'dataset themes/categories' on datos.gob.es, with examples (Economy, Health, Transport). It distinguishes itself from the sibling 'datasets' tool by specifying its use as a filter.

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 tells the agent to use this tool 'as a filter in the datasets tool', providing clear context. However, it does not explicitly mention when not to use it or alternatives beyond the implicit distinction from 'datasets'.

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

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

Discloses that the row is deactivated not deleted and historical events remain available via recent_alerts. Annotations provide idempotentHint=true and destructiveHint=false, and the description adds context beyond annotations. No contradiction.

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

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

Two concise sentences front-loaded with purpose and enforcement. Every sentence adds 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?

For a simple mutation tool with one parameter and no output schema, the description covers ownership, deactivation behavior, and historical data availability. Annotations provide safety hints, making it complete.

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

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

Schema description coverage is 100% with clear parameter description 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no additional 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?

Description clearly states 'Cancel a subscription by id' with specific verb 'cancel' and resource 'subscription'. Adds ownership enforcement and deactivation behavior, 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?

Explicitly states 'you can only cancel your own subscriptions', providing clear context for when to use. Does not mention alternatives or when not to use, but the constraint 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?

Annotations already declare readOnly/idempotent/openWorld/destructive=false, so the safety profile is covered. The description adds significant behavioral nuance by explaining that 'could_not_verify' means the check did not happen and must not be treated as evidence, and distinguishes it from 'unsupported'. This goes beyond what annotations provide.

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

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

The description is front-loaded with natural-language query examples and a clear purpose statement. It is dense but information-rich, covering routing, return values, and caveats in one paragraph. While every sentence adds value, the length could be slightly reduced without losing the critical warnings about could_not_verify.

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

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

Even without an output schema, the description fully enumerates the possible verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), describes the citation format, and explains the error field (verification_error{stage,detail}). It also mentions the efficiency benefit of replacing 4-6 sequential calls, making it self-sufficient for a 2-parameter 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% for both parameters (claim and tolerance_pct), including examples and default behavior. The description adds context about the 'exact percent-delta math' and 'hallucination detection' use case, but this is largely illustrative rather than necessary semantic detail; the schema already carries the full parameter meaning.

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 verifies natural-language factual claims against authoritative sources, with specific example phrasings ('fact check', 'verify the claim that…'). It also distinguishes two distinct verification paths (SEC EDGAR/XBRL fast path vs. generic grounded pipeline), setting it apart from sibling Q&A tools like ask_pipeworx_grounded.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear trigger. It also explains the routing logic for company-financial vs. any other claim, which implies when the tool is applicable. It doesn't name alternative sibling tools explicitly, but the use-case instruction is strong.

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