Dati It

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it scores visibility (0-100), returns per-model raw_response, and notes Anthropic requires own API key with direct payment. 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?

Single paragraph with efficient sentences. Purpose and action are front-loaded. Return format and use cases are included without redundancy. Slightly dense but well-structured.

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

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

Given 100% schema coverage, annotations, and multiple similar siblings, the description is complete: it covers purpose, parameters, return format, and use cases. No missing critical information for an AI agent to use the tool correctly.

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

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

Schema description coverage is 100% (baseline 3). Description adds value by explaining '_apiKey' is passed straight through to api.anthropic.com and that users pay directly, and clarifies 'context' helps disambiguate common names. 'models' parameter usage is explained.

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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes from sibling tools by focusing on visibility scoring across models.

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

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

Provides explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains default model and optional API key for Anthropic. Does not explicitly compare to siblings like 'scan_competitor_ai_presence' or 'entity_profile', but context is clear enough for appropriate use.

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

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

Annotations already indicate a read-only, idempotent, non-destructive tool, and the description adds meaningful behavioral context: the tool routes to other tools, fills argument slots automatically, and returns structured answers with stable pipeworx:// URIs. It does not contradict the annotations, though it does not detail failure modes or latency.

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

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

The description is long but front-loaded with the key directive and scannable across use-cases, examples, and alternatives. Some redundancy exists between 'current or historical data' and the later 'current' trigger list, but overall it earns its length for a catch-all routing 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?

Without an output schema, the description still explains what the return looks like (structured answer with citations), when to use the tool, and when to use sibling tools. It is sufficiently complete for an agent to call it correctly, though it does not specify what happens if the question is unsupported or unanswerable.

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

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

Schema description coverage is 100%: the required question parameter and its aliases are already fully documented in the schema. The description adds natural-language examples and the notion that the tool fills its own internal arguments, but it does not materially add to what the input schema already states.

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 names a specific action with a clear resource: it routes natural-language questions to one of many verified data tools and returns structured answers with pipeworx:// citations. It is not a tautology and clearly distinguishes this tool from generic web search, ask_pipeworx_grounded, and deep_research.

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

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

The description gives strong usage direction: PREFER OVER WEB SEARCH, explicit trigger phrases, concrete example questions, and explicit when-not-to-use guidance by routing to ask_pipeworx_grounded or deep_research. It also covers time-sensitive news cases.

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

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

Annotations already provide the safety profile: read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond the annotations by explaining the beta nature, the live candidate-switching mechanism, the current retired-candidate state, and the fact that this is a fully functioning router with no fallback behavior.

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

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

The description is front-loaded with the most valuable information: it is a beta router with the same universal toolset, current state, and how to use it. It is a bit over-explained in the middle with the retirement date and the emphatic clarification that it is truly a working router, but those details genuinely improve behavioral transparency without being too wasteful.

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

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

For a tool with no output schema, the description is quite complete: it explains the response shape by referencing ask_pipeworx, describes the current runtime behavior, and clearly states what the tool is and is not. It leaves out, reasonably, the internal routing details, but the agent has enough information to invoke 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?

Schema description coverage is 100%, so the schema already documents all parameter semantics, including aliases and the natural-language question field. The description's only parameter-related statement is 'same arguments', which adds no meaning the agent didn't already get from the schema. A baseline of 3 is appropriate when the schema handles the parameter burden.

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

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

The description names a specific function: a beta version of ask_pipeworx with identical routing scope, argument set, and response shape, but with possible experimental routing changes. It distinguishes itself from ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental edge, so the agent can select it without guessing.

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 guidance is explicit: use it exactly like ask_pipeworx when the agent wants the newest routing, and know that results are compared against the stable router for study. It also states that the current behavior exactly matches ask_pipeworx, giving clear selection context and implicitly highlighting the stable alternative.

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

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

The description discloses a detailed behavioral contract beyond the annotations: the success response shape, the explicit refusal shape, the possible refusal_reason values, and grounding in only the fetched tool output. It contradicts no annotations and complements readOnlyHint, idempotentHint, and openWorldHint 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?

The description is front-loaded with the most important distinction, then gives the return contract, refusal behavior, usage policy, and cost comparison. Every sentence carries meaningful decision-relevant information with no filler or repeated schema content.

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

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

With no output schema present, the description fully compensates by specifying the success and failure return structures, including example refusal_reason values. It is complete enough for an agent to decide both whether to use the tool and what to expect afterward.

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

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

The input schema already documents the question parameter fully, including natural-language input and accepted aliases. The description adds no parameter-specific detail beyond the schema, so it sits at the baseline for a high-coverage 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?

States the mode clearly: hallucination-resistant, high-stakes, grounded answer extraction. It distinguishes itself from ask_pipeworx by explaining that the answer is generated only from the fetched tool result and that it returns evidence, confidence, and refusal reasons.

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

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

Explicitly says when to use: when answers will be quoted, cited, or acted on in contexts requiring factual reliability such as financial, legal, medical, or public-statement lookups. Also explicitly names ask_pipeworx as the cheaper alternative for casual lookups and notes the extra LLM call cost.

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 extensively covers behavioral traits beyond annotations: fan-out patterns, response shapes (market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent_event extraction, news fallbacks, safety short-circuits, spread warnings, and resolution-rule risk. This adds significant context beyond readOnlyHint and idempotentHint 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 lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with the core purpose. While some details could be condensed, the structure aids reading for a complex 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?

Despite no output schema, the description thoroughly covers return fields, edge cases (low-confidence match, closed markets, wide spreads), error states, and caveats (resolution-rule risk). It provides complete context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description adds meaning: explains depth default (thorough), include_raw default (false) with use cases, and clarifies market input formats (slug, URL, question text). This goes beyond the schema descriptions, providing practical guidance.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on different aspects.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides usage examples. It also advises checking market_match_confidence before trusting analysis. However, it does not explicitly exclude sibling tools or state when not to use this tool.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. The description adds behavioral details: pulls from SEC EDGAR/XBRL for companies (with fiscal year handling), FAERS for drugs, returns sorted results, and includes citation URIs. No contradictions.

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

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

The description is front-loaded with example queries, then explains data sources and sorting. Every sentence adds value, though slightly verbose. Could be trimmed without loss.

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

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

With only 2 simple params and no output schema, the description fully explains what each type returns, how results are sorted, and that citations are included. The tool's complexity (data sources, fiscal handling) is adequately covered.

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?

Despite 100% schema coverage, the description adds meaning: explains the purpose of each enum value (e.g., 'company' pulls financials, 'drug' pulls adverse events) and provides concrete examples for values (tickers/CIKs for company, drug names).

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

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

The description specifies a clear verb+resource ('side-by-side comparison') and lists specific user queries (e.g., 'X vs Y', 'rank these companies'). It distinguishes from sibling tools by explicitly stating it replaces 8–15 sequential lookups and is preferred over single-pack lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. It lacks explicit when-not scenarios but the preference is strong 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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds explicit constraints: no datastore, no row-level API, and that resources have directly fetchable URLs. 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 sentences, front-loaded with purpose, followed by essential behavioral notes. 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?

For a single-parameter read tool with no output schema, description covers all needed: what it returns (full record with resources) and how to use the data (fetch URLs). Annotations cover safety. 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 already covers parameter fully (UUID or slug). Description only restates 'by id or slug', adding no new semantics beyond schema.

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

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

Description clearly states 'Full dataset record by id or slug' and mentions resources and download URL. Distinguishes from search_datasets and organization_details.

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

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

Explains when to use (by id or slug, need full record) and notes lack of row-level API, implying when not to use. Does not explicitly name alternatives but context suffices.

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, the description discloses notable behaviors: authentication and paid-tier requirements, latency ranges, not open-web, gap recovery hops, contradiction detection, never inventing gaps, and citation_uri fetchability. These materially help an agent set expectations and avoid common mistakes.

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

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

The description is long, but every major section serves a purpose: prerequisite, primary behavior, output shape, when-to-use arbitration, depth modes, and latency. A few facts like the paid requirement appear more than twice, and the text is dense, but the most important 'ACCOUNT REQUIRED' and 'not open-web' constraint are 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?

There is no output schema, so the description carries the full burden of explaining the return value, and it does except thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop, and probable latency classes. Combined with parameter details, this lets an agent select and invoke the tool without ambiguity.

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 records 100% coverage for both parameters, so the baseline is 3. The description goes further by adding behavioral meaning to depth (paid plan requirement, gap-recovery hop, contradictions scan, latency differences), which gives the agent context beyond the schema's static enum 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 states a specific verb and resource: it runs grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly differentiates itself from open-web search and from siblings like ask_pipeworx and bet_research, making its 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 gives explicit selection guidance: use ask_pipeworx when not signed in, ask_pipeworx for single lookups and breaking/colloquial current-news topics, and deep_research for broad/multi-part structured-data questions. This is concrete alternation routing with clear conditions.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results include full schemas and are ready to call directly, which is useful context. No contradiction with annotations.

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

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

Description is dense but front-loaded with purpose and specific outcomes. Every sentence adds value; however, the list of domains is somewhat lengthy but informative. 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?

No output schema, but description explains return format (top-N tools with names, descriptions, schemas) sufficiently. For a tool discovery function, this covers what an agent needs to know.

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 examples. Description mentions 'Natural language description' for query but adds little beyond schema. Baseline 3 is appropriate as schema does the work.

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

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

Description clearly states the tool finds tools by describing data/task, listing many domains. It distinguishes from siblings by advising to call this first to see options. Specific verb 'discover' and resource 'tools' with clear scope.

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

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

Explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist'. Additionally advises 'Call this FIRST when you have many tools available and want to see the option set'. No explicit when-not, but context implies alternatives are task-specific tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: it fans out across multiple sources, soft-fails on patents, and lists exact return fields. 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 detailed yet concise. It front-loads the purpose and usage, then lists outputs in a structured manner. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description enumerates all return fields (cik+company_name, recent_filings, fundamentals, patents, news, LEI) and covers limitations (patents sunset, names not supported). This provides complete context for the agent.

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

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

Schema coverage is 100% for 2 parameters. The description adds meaning beyond the schema: it explains that 'value' can be ticker or zero-padded CIK with examples, and clarifies that 'type' only supports 'company'. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs ('research,' 'brief me on') and distinguishes from siblings like resolve_entity by noting that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an alternative: use resolve_entity first if you only have a name. This gives clear guidance on when to use this tool vs alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which aligns with the destructive nature but does not contradict annotations.

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

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

The description is three concise sentences with the action stated first. 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 one parameter and destructive annotation, the description fully covers purpose, usage context, and tool relationships. No output schema needed.

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 parameter 'key' is well-described. The description does not add 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 the action ('Delete a previously stored memory by key') and distinguishes the tool from siblings like 'remember' and 'recall'.

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

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

Explicitly provides when to use the tool ('stale context', 'task done', 'clear sensitive data') and references alternative tools ('Pair with remember and recall').

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds context: fetching an external URL, extracting title/description/key links, and emitting standard markdown. It does not contradict annotations.

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

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

The description is concise: three sentences plus a list of use cases. It is front-loaded with the main purpose and contains zero wasted words.

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

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

For a simple tool with 2 parameters and no output schema, the description covers input (URL, optional max_links), process (fetch, extract, emit), output format (markdown text blob), and use cases. It lacks explicit error handling details but is sufficiently 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%, so baseline is 3. The description adds an example for url ('https://example.com' or a specific landing page) but nothing substantial beyond schema for max_links.

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

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

The description clearly states the tool generates an llms.txt file for any URL, detailing the process (fetch, extract, emit) and uses. It distinguishes from siblings by focusing on file generation rather than visibility checks.

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

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

The description gives explicit use cases (client site indexing, personal projects, competitor auditing), providing context for when to use. However, it does not explicitly exclude alternatives or mention when not to use the tool.

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

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

Annotations already declare readOnlyHint and idempotentHint true, so the tool is safe. The description adds that it uses CKAN group_list with full fields, providing technical detail and return shape 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 a single sentence that efficiently conveys purpose, scope, examples, and technical source without any wasted words.

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

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

Given the tool has no parameters and no output schema, the description is complete: it explains the source, the nature of the data, and that full fields are returned. No gaps exist for its simplicity.

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

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

With 0 parameters, the input schema is vacuous. The description correctly adds no additional parameter info, meeting the baseline of 4 for zero-parameter tools.

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 lists thematic groups/categories on dati.gov.it, with specific examples like Agricoltura, Salute, Trasporti. It uses a specific verb-resource combination and differentiates from sibling tools like list_organizations by focusing on groups.

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

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

The description implies when to use (for listing thematic groups) but does not explicitly state alternatives or exclusions. The contrast with sibling list_organizations is inferable but not 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds that it returns slugs and is a CKAN list, reinforcing safety and usage boundaries.

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 that front-load the purpose and provide actionable next-step guidance.

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 and no parameters, description fully covers what the tool does, its return format, and how to get detailed records, leaving no ambiguity.

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

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

No parameters exist in schema (0 params, 100% coverage), so baseline is 4. Description does not add parameter info as none needed.

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

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

Description clearly states it lists publishing organizations from dati.gov.it via CKAN organization_list, specifies return value (slugs), and distinguishes from sibling tool organization_details.

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

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

Provides clear context for when to use this tool (to get a list of slugs for further lookup) and references an alternative (organization_details) for full records, though no explicit when-not-to-use.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying that only 'active' subscriptions are returned by default and that the response includes specific fields, which informs the agent about expected output.

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

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

The description is two sentences, no redundant words. It front-loads the core function and immediately lists returned fields, then provides usage guidance. Every sentence serves a purpose.

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

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

The tool is simple with one optional parameter and no output schema. The description covers the return structure, default behavior, and usage context. It might lack mentions of pagination or rate limits, but these are not critical for this tool's completeness.

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

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

Schema coverage is 100%, and the input schema already documents the include_inactive parameter well. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It also distinguishes from siblings like subscribe and unsubscribe by focusing on listing.

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

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

The description provides explicit usage contexts: reviewing subscriptions before adding more, and finding an ID to cancel. It does not cover when not to use, but the guidance is clear and actionable.

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, providing strong behavioral transparency. The description adds context about the returned fields (e.g., Italian display name, dataset count) without contradicting annotations.

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

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

The description is extremely concise with two sentences, front-loading the core purpose and key details. Every sentence is valuable and free of fluff.

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

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

For a simple read-only tool with one parameter and rich annotations, the description covers the return fields and input source. It does not discuss error scenarios, but that is acceptable given the low 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 the description does not need to add much. The description merely restates that the tool accepts a slug or id, matching the schema. No additional meaning is provided beyond what the schema already offers.

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

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

The description clearly states it returns the full record for one organization by slug or id, listing specific fields (Italian display name, description, dataset count) and referencing the CKAN organization_show API. This distinguishes it from sibling tools like list_organizations.

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

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

The description advises to get the slug from list_organizations or a dataset record, providing a clear usage hint. It does not explicitly discuss when to use this tool over alternatives like dataset_details, but the context is sufficient.

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

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

Despite no strong annotation hints (only false flags), the description discloses important behavioral details: the rate limit of 5 per identifier per day, that it is free and does not count against tool-call quotas, the claim_token flow for checking status, and that reports are read in daily digests. This far exceeds the minimal information normally expected and gives the agent concrete expectations for side effects.

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

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

The description is long but every clause carries operational value: purpose, scope boundaries, claim_token mechanics, rate limit, and roadmap impact are all packed into distinct sentences. It is front-loaded with purpose and then layers usage and behavioral guidance in a logical order without repetition or filler.

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

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

With no output schema and a nested parameter object, the description compensates by explaining the return type (claim_token), the resolution flow, the audience, and the scope limitations. It also clarifies what not to send (don't paste end-user prompts) and how to identify the relevant tool, making it complete for the tool's complexity.

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

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

The input schema already provides 100% descriptive coverage for all parameters, including enums and nested fields. The description adds value by prescribing message style ('Be specific... 1-2 sentences typical, 2000 chars max') and by explaining the claim_token interaction pattern beyond the schema's syntax, which earns a score slightly above the 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 opens with a specific verb plus resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately clarifies the feedback categories and names the target audience, which fully distinguishes this tool from all documented siblings.

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

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

The description explicitly states when to use the tool (e.g., 'Use when a tool returns wrong/stale data') and when not to use it: if the tool came from a different MCP server, report it there instead. It also provides a disambiguation heuristic for identifying Pipeworx tools and notes rate limits, making usage conditions unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds substantive behavioral context: caching (5min-1h), data source (CF analytics-engine), no PII, and return content shape. This goes beyond annotations without contradiction.

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

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

The description is well-structured: core purpose first, then bulleted use cases, then technical details (caching, data source). Every sentence adds value with no redundancy or filler. Highly concise and front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all key aspects: what is returned (top tools, packs, volume), data source, caching behavior, and usage scenarios. While it lacks exact output format, it is sufficiently complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100% with a clear explanation of the window parameter and its trade-offs. The description repeats this info but does not add new meaning; it adequately complements the schema, meeting the baseline for high 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 tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('returns') and resource ('what other AI agents are calling on Pipeworx'). The three use cases distinguish it from siblings like ask_pipeworx or discover_tools, 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 provides three explicit use cases (discovering hot data sources, confirming canonical tool choice, checking alignment of use case). While it does not explicitly exclude sibling tools, the context implies when to use this tool versus alternatives, e.g., before asking a question.

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

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

Annotations already indicate read-only and safe behavior, but the description adds rich behavioral context: monotonicity checks, partition sum evaluation, semantic anchor similarity threshold, placeholder filtering, and fill check against live depth. 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 dense but well-structured, with front-loaded purpose and clear mode breakdown. Some technical details could be compressed, but every sentence serves a purpose for an AI agent. Minor verbosity prevents a perfect score.

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

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

Despite lacking an output schema, the description provides a thorough account of the response format (opportunities array with fields, partition_check object in event mode), fill check logic, and edge cases. Sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with brief descriptions, but the tool description adds substantial meaning: examples of valid inputs ('fed-decision-may-2026'), explanation of what each mode does internally, and what kind of results to expect. Goes far beyond the schema alone.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains when to use each, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. Provides recommendations and mentions alternative tools for custom sizing (polymarket_fill_risk), giving clear guidance on tool 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 indicate readOnlyHint, idempotentHint, and no destructive behavior. The description extensively details output structure (by_segment, diagnostics), caching behavior (1h at KV level), and reliability caveats (Fed signal unreliability). 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: introductory purpose, detailed model explanations, opportunity content, knob descriptions, and response layout. It is front-loaded with purpose but could be more concise; however, every section earns its place.

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

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

Given 9 parameters, no output schema, and rich annotations, the description is highly complete. It explains output structure, diagnostics, caching, and usage guidance for all knobs, leaving no ambiguity for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context beyond schema descriptions, explaining parameter purposes (e.g., min_kelly filters small opportunities, max_spread_pp ensures tight books) and trade-offs, helping agents use knobs correctly.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for finding betting opportunities. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on model-driven and structural arbitrage opportunities with detailed model explanations.

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

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

The description provides clear usage context: 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' It does not explicitly state when not to use or mention alternatives, but the context and model details imply appropriate use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: 60-day TTL, snapshot timing, decay computation (daily closes, not intraday), and interpretation of gaps. 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 relatively long but front-loaded with the core purpose. Every sentence adds useful information, though the response format details could be slightly more concise. Still, it is well-structured for an AI agent.

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

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

No output schema exists, so the description fully explains the response structure (tracked, expired, snapshot_dates) with field semantics, limitations (TTL, gaps), and decay interpretation. Complete for a read-only telemetry tool with simple optional params.

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 descriptions. The description adds context for defaults (days=14, window='1wk') and constraints (days max 30, clamp 2-30), reinforcing and slightly extending the schema information.

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

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

The description opens with a specific verb+resource ('Edge persistence and decay telemetry built from daily polymarket_edges snapshots') and clearly states the question it answers. It contrasts with sibling polymarket_edges (raw snapshots) by focusing on temporal analysis.

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

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

The description explains the tool's value (distinguishing fresh vs. old wide edges) and implies when to use it. It does not explicitly state when not to use or name alternatives beyond the sibling context, 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 declare read-only, idempotent, and non-destructive nature. The description adds significant behavioral context: walking the ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, and warnings about forced directional risk. No contradiction with annotations.

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

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

The description is well-structured with line breaks and bold for key terms. It front-loads the core purpose and then explains modes. While informative, it is somewhat lengthy but the structure aids readability.

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

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

Given the complexity (two modes, many output fields) and no output schema, the description is exceptionally complete. It details both modes, all parameters, return fields, and critical warnings about real-world implications (e.g., partial fills converting to directional positions).

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 meaning beyond the schema by clarifying side options per mode, explaining size_usd interpretation (max spend for buys, target proceeds for sells in single-market; settlement notional for basket), and detailing the purpose of each 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 defines the tool as a realizable-vs-theoretical edge check against live order-book depth, with specific verbs and resource description. It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also explains why (theoretical overround not always capturable, partial fills create directional risk) and specifies required parameters (market or event).

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral details: compatibility warnings (non-equivalent bet shapes, semantically unrelated events), temporal alignment, and skipped cross-type/cross-subtype counters. 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 comprehensive but somewhat lengthy; however, every sentence adds value (modes, response structure, safety fields). It is front-loaded with the core purpose and well-organized with clear sections, though could be slightly more concise.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety warnings), the description is nearly complete. It explains response fields (leg-by-leg prices, top_spreads_pp, compatibility warning, temporal alignment) despite no output schema. All critical aspects are covered.

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

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

Schema coverage is 100% but the description adds crucial context beyond schema: explains the two modes, how topic values auto-map, and how explicit tickers override. For example, it clarifies that 'topic: fed' auto-fetches matching events on both venues, which the schema alone does not provide.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs and resources ('spread', 'cross-venue') and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue price differences.

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 modes ('topic' vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, indicating when not to rely on results. However, it does not explicitly compare to alternatives like polymarket_arbitrage or suggest when to use them.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable context about scoping to an identifier (IP, key hash, account ID) and pairing with remember/forget.

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

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

The description is concise (3-4 sentences), front-loaded with the primary function, and every sentence adds value. 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?

Without an output schema, the description explains what is returned (value or list of keys) and addresses scoping. For a simple tool with one optional parameter, this is nearly complete.

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

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

Schema coverage is 100% with schema description already explaining the key parameter. The description adds examples of what keys might represent (ticker, address, notes) but does not add substantial new semantic information 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 retrieves a value saved via remember or lists all keys, using specific verbs and resources. It distinguishes from sibling tools like 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 gives clear context for use: look up stored context without re-deriving. It mentions scoping and pairing with remember/forget but does not explicitly state when not to use it.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds specifics: returned fields (source, citation_uri), raw payload, and mark_read side effect that flags events as read, affecting subsequent calls. 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?

Single paragraph, front-loaded with main purpose. Efficient, but could use bullet points for readability and better separation of parameter details.

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

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

Covers return fields, filtering, and mark_read effect. Missing explicit mention of ordering (assumed recency) and pagination. No output schema, but description compensates well. Most actions are covered.

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema by providing examples for type format ('sec_8k') and explaining mark_read behavior, but does not elaborate on limit or unread_only 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?

Description uses specific verb 'Pull' and identifies resource as 'fired events from your subscription feed'. It details returned fields and filtering options, clearly distinguishing it from sibling tools like list_subscriptions or search_within.

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

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

Provides guidance on polling and an alternative access method (GET registry.pipeworx.io/alerts.json). Does not explicitly state when not to use this tool, but the context of subscription feed retrieval is clear and distinct from siblings.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds valuable context: fan-out to multiple sources (SEC, GDELT→GNews fallback, USPTO), fallback logic, soft-fail for USPTO, and return structure.

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 clear and front-loaded with examples. It contains multiple sentences but each adds value. Could be slightly more concise but effectively conveys purpose.

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

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

For a tool with 3 required parameters and no output schema, the description covers return structure, sources, fallback, and usage notes, making it complete for the given complexity.

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

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

Schema covers all parameters with descriptions. The description adds context about the tool's behavior and sources but does not significantly expand parameter meaning beyond what the schema provides.

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

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

The description provides explicit example queries and states the tool is a change feed for a company in a time window, clearly distinguishing it from the sibling tool entity_profile which serves static profiles.

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

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

The description explicitly contrasts with entity_profile, advising when to use each tool. It also gives usage examples like '30d' for typical monitoring.

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

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

Disclosures beyond annotations: scoped by identifier, persistence based on authentication status, pairing with recall and forget. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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, all essential. Purpose is front-loaded. No redundancy. Every sentence earns its place.

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

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

Complete for a simple key-value store tool with two parameters, no output schema, and annotations covering safety and idempotency. Addresses persistence, scoping, and sibling tool interactions.

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 input schema (100% coverage). The description reinforces these but adds no new parameter-specific information beyond usage context; 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?

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from sibling tools recall and forget by mentioning them as pairing tools.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides concrete examples. Also differentiates from recall and forget, and addresses persistence differences between authenticated and anonymous sessions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds rich behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, cascading internal lookups, explicit resolution of unresolved identifiers, and source-labelled outputs. This exceeds 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 dense but every sentence earns its place: it front-loads purpose with examples, then covers supported types, failure behavior, and internal cascading. Despite its length, it remains structured and without redundancy, appropriate for the tool's complexity.

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

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

With no output schema, the description must explain return values, and it does: it details what identifiers are returned for companies and drugs, how unresolved items are reported, and how enrichment degrades. It is complete for an entity resolution tool of this complexity.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining entity-type-specific semantics (e.g., ISIN resolves to legal entity, drug returns RxCUI plus ingredient/brand) and providing concrete value examples for each type. This adds substantial meaning beyond structured definitions.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical identifiers required by other tools. It includes multiple example queries and explicitly says to use it 'FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools that consume identifiers.

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

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

The description provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and enumerates natural-language query patterns. It does not explicitly name alternatives or conditions for non-use, but the directive is strong enough to effectively guide an agent.

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

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

Annotations already declare readOnly, idempotent, openWorld hints. Description adds that it internally calls ai_visibility_check for each entity, ranks by score, and returns a ranked list with score, confidence, signal density. No contradiction with annotations.

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

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

Two concise sentences plus an illustrative example. Every sentence contributes meaningful information. Highly efficient and front-loaded with core purpose.

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

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

Given 4 parameters, 100% schema coverage, no output schema, and good annotations, the description explains overall workflow, output format, and use case. Lacks minor edge cases but sufficient for the complexity level.

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

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

Schema coverage is 100% with descriptions. Description adds semantics like 'First entry treated as the subject for narrative' and explains tradeoffs for models (free vs requiring API key) and context purpose. Adds value beyond schema.

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

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

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 distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (other comparisons).

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 explicitly says 'Useful for competitive AI-marketing audits' and provides an example question. While it doesn't explicitly state when not to use or list alternatives, the sibling context strongly implies single-entity tools exist for individual probes.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context: partial failures, bundlephobia timeout (5-30s), graceful degradation with sources_failed list, and return structure details.

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

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

The description is a single dense paragraph but efficiently conveys purpose, usage, limitations, and output structure. Every sentence serves a purpose, though it could be slightly more structured with bullet points for the return fields.

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

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

No output schema, but the description details all return fields. Parameter schema is fully covered. The tool complexity (composite, external dependencies) is well addressed with timeouts and failure modes. Additional context like ecosystem scope and partial failure handling makes 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining default version behavior (latest when omitted), acceptance of scoped packages, and outlines the output fields (summary block, advisory detail, links, alternative versions), which is not in the schema.

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

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

The description specifies the tool is a composite 'should I add this npm package' check, covering licenses, advisories, version history, bundle size, and tree-shaking support. It distinguishes from siblings by focusing on npm ecosystem and single-call evaluation.

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 an agent asks about safety, popularity, size, or cost of adding an npm package. It also directs agents to deps.dev for non-npm ecosystems, providing clear alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. Description adds that results are mostly Italian and mentions the underlying API, which is helpful but not transformative. No contradiction with annotations.

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

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

Two efficient sentences with no waste. The first sentence states the action and resource; the second adds key language insight. Front-loaded and clear.

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

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

Given the complexity (5 params, no output schema), the description covers the essential functionality and query language behavior. It does not describe return fields explicitly, but the tool is standard enough that this is acceptable.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minor value by noting that Italian queries yield more results, complementing the query parameter's description.

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

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

Description clearly states the tool searches the dati.gov.it catalogue of Italian public-administration open data, using CKAN package_search. It distinguishes from sibling tools by targeting a specific authoritative source and language context.

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 context on query language effectiveness (Italian matches far more) but does not explicitly state when to use this tool versus siblings or give exclusions. Implicit usage guidance is present but not 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?

Discloses internal details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. Annotations already indicate read-only, idempotent, non-destructive; description adds value beyond annotations with no contradictions.

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

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

Two concise paragraphs, no redundant sentences. Front-loaded with core purpose, followed by usage guidance and technical details. Every sentence adds value.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and similarity scores), limits, truncation behavior, and pairing with sibling. Complete for an agent to understand inputs, outputs, and constraints.

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

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

Schema covers all three parameters with descriptions. Description adds concrete examples for query (e.g., 'supply-chain risk'), context for text ('SEC 10-K body, article'), and clarifies limit default (5) and range (1-20). Slightly above baseline as schema coverage is 100%.

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 'Semantic search INSIDE a fetched record' and specifies the inputs (text and query) and outputs (passages with offsets and scores). It distinguishes from sibling tool ask_pipeworx_grounded by explaining the pairing use case.

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

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

Explicitly advises to use when the record is too large for the prompt and mentions pairing with ask_pipeworx_grounded for grounding, providing clear when-to-use and alternative guidance.

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

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

Description adds context beyond annotations: requires OAuth, delivery channels with constraints (SMS cap, webhook auto-disable), and examples. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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

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

Well-organized: purpose, requirement, types, delivery. Slightly long but every sentence adds value; no fluff.

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

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

Covers prerequisites (OAuth), return value (subscription ID), type-specific parameters, delivery channel details with constraints. No output schema, but description explains output sufficiently.

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

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

Schema coverage is 100%, and description adds detailed format and examples for each parameter (e.g., sec_8k params, delivery subfields with HMAC signing explanation). Significant added value beyond schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It lists specific types (sec_8k, polymarket_edge, etc.) and delivery channels, distinguishing it from sibling tools like 'unsubscribe' 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?

It specifies that a Pipeworx OAuth account is required (anonymous/BYO cannot persist), and details per-type parameter requirements and delivery options. However, it does not explicitly state when not to use this tool or mention alternatives besides the implied siblings.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral details: it returns example questions with tool argument shapes, is an onboarding entry point, and can be called with no arguments or a topic. 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 relatively long but front-loaded with the main purpose. Each sentence adds value—clarifying when to use, what to expect, and optional parameter behavior. Could be slightly more concise, but very well structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers what the tool does, when to use it, what it returns (category-bucketed examples with tool shapes), and how to call it. No missing crucial details.

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

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

Schema coverage is 100% with one optional parameter. The description explains the purpose of the topic parameter, lists example focus areas (finance, pharma, etc.), and states that omitting it gives a full spread. This adds significant meaning beyond the schema's basic 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 is an onboarding entry point returning category-bucketed example questions. It uses specific verbs like 'get started' and 'learn what to ask', and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on exploration rather than answering queries.

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

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

The description explicitly states to use this tool FIRST when the agent doesn't know what Pipeworx can do. It also provides guidance on alternatives: mentions meta-tools (ask_pipeworx, entity_profile, etc.) implicitly as what you learn about, and the optional topic parameter allows narrowing focus.

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 (idempotent, non-destructive), the description adds critical behavioral details: ownership enforcement, soft-delete via deactivation, and preservation of historical events accessible via 'recent_alerts'.

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

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

Two sentences, front-loaded with purpose, no redundant phrases. Every sentence adds value: action, ownership, deactivation behavior.

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-parameter mutation tool with no output schema, the description fully covers purpose, constraint, behavior, and consequence. Siblings 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?

The schema already provides full coverage for the single parameter 'id' with its description. The tool description adds no new parameter semantics beyond restating the purpose.

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 'Cancel a subscription' and the resource 'by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the action and ownership enforcement.

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

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

The description provides usage context: ownership enforcement and deactivation behavior. It implicitly tells when to use (cancel own subscription) but lacks explicit when-not or alternative tool suggestions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial transparency beyond these: it describes the two distinct execution paths (SEC EDGAR fast path vs. grounded pipeline), the verdict taxonomy, and the critical caveat that 'could_not_verify' must not be treated as evidence. It also discloses the `verification_error` structure and the meaning of 'unsupported', which is valuable behavioral context not present in annotations.

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

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

The description is verbose but every sentence carries essential information — from trigger phrases to routing logic to verdict semantics to the 'replaces 4–6 sequential calls' efficiency statement. It is front-loaded with the most critical use-case indicators. Slightly dense, but not bloated; each clause adds value. A 5 would require even tighter wording, but the content justifies the length.

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

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

Given the tool's complexity (two distinct pipelines, multiple verdict categories, error handling, no output schema), the description is remarkably complete. It explains what the tool returns (verdict, actual value, citation, reasoning), what each verdict means, and why 'could_not_verify' is distinct from 'unsupported'. The missing output schema is compensated for by the detailed return-value description. The description fully prepares an agent to use the tool correctly in varied contexts.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by providing concrete examples for the 'claim' parameter and explaining 'tolerance_pct' semantics (overrides implied tolerance, caps at 5, recommended 1–2 for hallucination detection), which goes beyond the schema's generic 'Max percent deviation' description. The description also ties the parameter behavior to the verdict outcomes, giving context on how the parameter affects results.

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

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

The description opens with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by stating it 'replaces 4–6 sequential calls' and covers both structured and grounded pipelines. The purpose is unambiguous and differentiates from alternatives.

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 whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic for company-financial vs. other claims. It also notes that 'could_not_verify' means the check did not happen, clarifying a key edge case. However, it does not explicitly name when NOT to use this tool (e.g., versus deep_research for open-ended research), relying on the 'fact check' framing to imply scope.

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