Openfema

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

Annotations provide safety hints (readOnly, idempotent). Description adds valuable behavioral details: return format includes per-model {score, confidence, signals, raw_response} and combined view, and that Anthropic calls pass through to api.anthropic.com with direct billing. 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?

Three sentences, front-loaded with core purpose, then details, then use cases. No wasted words.

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

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

No output schema, but description covers return structure well. All parameters explained. Context signals (100% coverage, 1 required param) support completeness. No gaps for agent to select and invoke.

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

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

Schema covers all 4 parameters with descriptions. Description adds nuance: default model is free, _apiKey is optional for Anthropic, context helps disambiguate. Adds meaning beyond schema.

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

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

Description uses specific verb 'probe' and resource 'LLMs', states output 'visibility (0-100) per model', and distinguishes from sibling tools like 'ask_pipeworx' by targeting any entity and focusing on visibility scoring, not question-answering.

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?

Clearly states default model and when to pass _apiKey for Anthropic, gives use cases (AI-marketing audits, pre-launch checks). Lacks explicit when-not-to-use or alternative tools, but 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?

Annotations already declare readOnly, openWorld, and idempotent hints, and the description complements them with concrete behavioral context: routing across a massive tool network, filling arguments, returning structured answers with stable citation URIs, working on every tier, and making 'one fast call'. It stops short of describing failure modes or upper bounds, but supplies meaningful beyond-schema detail.

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: it leads with the most important directive, provides examples in a compact list, and closes with actionable alternatives. Some repetition exists ('START HERE' and 'default entry point') and 'Use whenever' could be tighter, but each section earns its place for a central, broad-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?

For a tool that routes to thousands of sources and lacks an output schema, the description covers scope, use cases, output format (structured answer plus pipeworx:// URIs), and escalation paths. It could mention latency/cost trade-offs or how to handle ambiguous inputs, but overall it gives an agent enough 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 coverage is 100% and all six parameters are aliases for the same natural-language question, so the schema carries the load. The description adds value with concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifies the intended input style, going slightly beyond the schema's terse 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 uses a specific verb ('routes', 'returns') and names the resource (pipeworx's 5,529 tools across 1,455 sources) while clearly distinguishing itself from siblings like ask_pipeworx_grounded and deep_research. It answers factual questions with citations, making the 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?

Explicitly instructs 'PREFER OVER WEB SEARCH' and 'START HERE', lists query trigger phrases ('what is', 'look up', 'find'), and gives step-up alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is model-level usage guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description does not contradict that. It adds valuable context: it is an experimental edge, currently identical to stable, and 'falls back to nothing' because it is a fully working router.

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

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

The description is three sentences and mostly front-loaded with the core identity. It is slightly longer than necessary but every clause contributes distinct information (beta, current state, usage direction, fallback status).

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 a single required parameter and a thorough schema, the description fully covers the behavioral context: beta status, current equivalence to stable, comparison purpose, and guarantee that it is a full working router. No output schema exists, but the description promises the same response shape as ask_pipeworx, which is sufficient.

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

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

Schema coverage is 100% and lists all six alias parameters with descriptions. The description only repeats 'same arguments' without adding any new meaning beyond the schema, so it does not elevate beyond 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 clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with the same 5,529 tools and arguments. It distinguishes itself from the stable sibling by describing its experimental role ('candidate routing improvements') and current inactive-candidate state.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives clear when-to-use guidance and sets expectations relative to the sibling ask_pipeworx.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds substantial behavioral context: the tool fetches data and extracts only from tool results, returns a structured success object with evidence, and provides explicit refusal reasons in failure cases (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost, which is valuable 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 longer than minimal but front-loads the core purpose and every sentence adds useful information. The internal details of 'picks the right tool from 5,529 across 1455 sources' are slightly verbose but help contextualize the tool's behavior. Overall, it is well-structured with a clear flow from purpose to usage to cost tradeoff.

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 correctly takes on the burden of explaining return values and refusal reasons, which it does in full detail. It also covers use cases, cost, and routing context, making the tool's behavior and limitations clear for high-stakes decision-making.

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

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

Schema coverage is 100% and all six parameters are aliases for 'question' with clear descriptions. The description does not need to elaborate on parameters, as the schema already covers them fully. It adds no additional param-specific guidance, but the baseline of 3 is appropriate when schema does the heavy lifting.

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

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

The description explicitly states the tool provides a 'hallucination-resistant answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains,' clearly identifying it as a grounded Q&A tool. It also distinguishes itself from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' and later 'prefer ask_pipeworx for casual 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?

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides a clear exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' naming the 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 extensively discloses behavior beyond annotations: resolver contract (confidence levels, alternatives, suggestions), parent_event extractor, news fallback fields, safety short-circuits (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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 sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). Every sentence provides necessary detail for correct usage. Slight verbosity is justified by 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?

Given no output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence), error handling (low_confidence_match, market_closed_or_inactive), and edge cases (wide spreads, cancellation rules). It is complete for an agent to understand 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 coverage is 100% with descriptions. The description adds value by explaining the 'market' parameter can be a slug, URL, or question text; 'depth' options with defaults; and 'include_raw' with recommendations. Examples further clarify usage.

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

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

The description clearly states the action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison). This distinguishes it from sibling tools, which are more narrow (e.g., polymarket_edges, ask_pipeworx).

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

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

Explicit use cases are listed: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Examples of fan-out for different bet types provide context. While it doesn't explicitly state when not to use, the description includes blocking mechanisms (low-confidence match, closed market) that act as implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the specific data pulled (e.g., revenue, net income, adverse-event counts), how off-calendar fiscal years are handled, and result sorting by primary metric. No contradictions.

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

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

The description is a single cohesive paragraph that effectively front-loads the core purpose ('Compare X and Y') and then elaborates on specifics. Each sentence adds value, though minor restructuring could improve scanability.

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?

While the description covers input and behavior well, it omits explicit detail about the output structure beyond 'paired data + pipeworx:// citation URIs.' Without an output schema, the agent would benefit from knowing the exact fields returned or format.

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

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

Schema covers 100% of parameters with descriptions. The description reinforces the parameter meanings by providing concrete examples (tickers vs drug names) and value ranges. It goes beyond schema by explaining what data is retrieved per type.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, specifying data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from sequential single-entity lookups with the phrase 'ALWAYS PREFER over sequential single-pack lookups.'

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

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

The description explicitly advises using this tool over sequential lookups and provides trigger phrases like 'X vs Y' and 'rank these companies.' It specifies entity types and cardinality (2-5), leaving no ambiguity about when to apply.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description adds extensive behavioral context: it explains the decomposition and parallel routing, the gaps[] mechanism (never invented), the hop-based iteration, contradictions[] scan, semantic excerpting, citation resolvability, and latency expectations. It also discloses account/paywall requirements and emphasizes this is NOT open-web search, giving a full behavioral profile.

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

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

The description is long but each sentence carries essential information for a complex tool, covering prerequisites, usage, output, limitations, and performance. It is well-organized, front-loaded with the critical account requirement and primary purpose, and weaves in details like source counts and tool routing that are relevant for trust and expectations. Some repetition with the schema's depth descriptions could be trimmed, but it is overall effectively 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?

With no output schema, the description fully explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[]) and processing model. It covers edge cases (gaps[], contradictions[], semantic excerpting for large records), alternatives, prerequisites, and latency. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains the practical implications of depth values (e.g., 'standard' re-angles unanswered gaps, 'thorough' adds a follow-up hop), the paid plan limitation for 'thorough', and latency expectations. It also clarifies that the question can be broad/multi-part, which complements the schema's 'natural language' note.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explicitly distinguishes it from open-web search and sibling tools. It specifies the verb (research), the resource (structured data sources), and the scope (broad/multi-part questions), and names alternatives like ask_pipeworx.

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: 'Best for broad/multi-part questions over structured data', and gives exclusions and alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also describes depth-tier usage and account requirements, making the tool's applicability very clear.

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

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

Beyond the read-only annotations, the description discloses crucial behavioral nuances: counts are DISTINCT DISASTERS by default, not table rows, and explains why (one row per county), including the Hurricane Harvey example. Also states the default ordering ('most recent first'), preventing misinterpretation of results.

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

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

Every sentence in the description carries valuable information: purpose, filter list, count behavior, date-range guidance, and ordering. Despite being dense, it avoids redundancy and is well-structured, front-loading the 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?

The description covers the tool's key behaviors and edge cases thoroughly, especially the count semantics and granularity controls. With no output schema, it could enumerate return fields, but the current detail is sufficient for selecting and invoking 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?

The input schema already has 100% coverage, but the description adds meaningful context by explaining the fiscal-year vs calendar-date distinction and how grain/designatedArea affect the output granularity. This goes beyond the schema's property descriptions, which are already detailed.

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 'Look up and COUNT US federal disaster declarations' and names the specific source (FEMA DisasterDeclarationsSummaries). This verb+resource combination distinguishes it from sibling tools, none of which target disaster declarations.

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

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

Provides explicit guidance on when to use since/until vs fiscal year, and explains the difference between disaster-level and area-level queries via designatedArea/grain. It does not explicitly name alternative tools, but gives clear contextual advice for common query patterns.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. Description adds value by explaining result format: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No 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?

Front-loaded with purpose and usage guidance. The list of example domains is somewhat lengthy but provides concrete context. No unnecessary sentences; each 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?

Given no output schema, the description adequately describes the return format (top-N relevant tools with schemas). The parameter explanations are complete, and the usage context is clear. Could hint at pagination or ordering, but not necessary for this 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%, baseline 3. Description adds context: explains that the query accepts multiple aliases (task, q, search, description) and is a natural language input. Also clarifies default and max for limit. This is useful beyond the schema property descriptions.

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

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

Clear verb+resource: 'Find tools by describing the data or task.' It distinguishes from sibling tools that are specific data lookups or actions, establishing discover_tools as a meta-tool for exploring the option set.

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

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

Explicit when-to-use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists specific domains, implying alternatives are the sibling tools for those domains.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds valuable context: the tool fans across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific data fields, and discloses that patents soft-fail due to API sunset. This covers potential failure modes and behavior 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 relatively long but uses a front-loaded structure with examples, followed by a clear purpose statement, and then a bullet-like list of returns. Every sentence adds necessary information. While it could be tightened, it remains well-organized for the complexity.

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

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

No output schema exists, so the description must detail return values. It does so comprehensively: cik, company_name, recent_filings (up to 5 with URIs), fundamentals (specific fields sorted), patents (with caveat), news, and LEI. It also notes the parallel call nature, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description adds meaning by explaining that 'value' accepts ticker or zero-padded CIK (and explicitly rejects names), and that 'type' currently only supports 'company'. This extra guidance aids correct parameter usage.

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

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

The description starts with numerous example queries that illustrate the tool's intent, then explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from sibling tools by indicating preference over chaining single-pack lookups, making the 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 clearly states when to use: 'when the user asks for a holistic view.' It also provides a specific exclusion: 'names not supported (use resolve_entity first if you only have a name).' The imperative 'ALWAYS PREFER over chaining...' gives strong guidance on choosing this tool over 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 provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and scenarios for deletion, aligning with annotations. No contradiction.

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

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

Two sentences, front-loaded with purpose, followed by usage guidelines. Every word serves a purpose 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?

Given low complexity (single parameter, no output schema, annotations present), the description sufficiently covers purpose, context, and usage. No further detail 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% with the parameter 'key' clearly described. The description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' and resource 'memory by key', clearly stating the function. It also distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. References alternatives by naming sibling tools, providing clear exclusions and guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context by describing the process (fetches page, extracts data, emits markdown) and output format (single text blob), which goes beyond what annotations provide.

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

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

The description is well-structured: it starts with the purpose, then details the process and output, and ends with use cases. Every sentence adds value, and there is no unnecessary information. It is concise yet comprehensive.

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 that there is no output schema, the description adequately explains the output format (standard llms.txt markdown, text blob). It covers the process and use cases sufficiently for an agent to understand the tool's behavior and output.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds value by providing examples for url ('https://example.com') and default/max values for max_links (default 25, max 50), enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for a URL. It differentiates from siblings by specifying the output format and use case, distinguishing it from related tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit usage scenarios: getting a client's site indexed, drafting for own project, auditing a competitor. It implies when to use this tool but does not explicitly state when not to use it, though the context is clear from the sibling tools.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by revealing that the output includes OData filter syntax and response shape documentation, which is useful context for downstream operations.

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

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

Two sentences, front-loaded with the core purpose, no redundant information. Every sentence serves a clear function.

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

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

Given no parameters, comprehensive annotations, and no output schema, the description is complete. It explains what the tool returns and how it should be used in conjunction with query_dataset.

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 zero parameters, the baseline is 4. The description does not need to add parameter details, but it explains what the output contains, which is relevant for understanding the tool's 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 tool lists OpenFEMA datasets with specific fields (entity name, version, description) and documents OData filter syntax. It differentiates from the sibling tool query_dataset by indicating it should be called first to discover targetable datasets.

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

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

Explicitly instructs to 'Call this first to discover what query_dataset can target', providing a clear usage sequence and purpose relative to a sibling 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 the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the returned fields and default behavior (active subscriptions only), providing context 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 two sentences, directly states purpose and usage, with no redundant information. It is front-loaded and efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers what it does, what it returns, and a usage scenario. It is nearly complete, though it could explicitly note that it only returns the caller's subscriptions.

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

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

The schema has 100% coverage for the single parameter 'include_inactive' with a clear description. The description only implies the default behavior but adds no additional meaning beyond the schema.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by indicating its use for reviewing existing subscriptions.

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

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

The description offers explicit guidance to use this tool for reviewing subscriptions before adding more or to find an ID to cancel. It implies when not to use it (not for creating or canceling) but does not explicitly mention alternatives or exclusions.

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 discloses behavioral traits beyond annotations, which only set all hints to false. It explains the claim_token flow (returns one if no account, and can be passed back later to read status), rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and user instructions like 'don't paste the end-user's prompt.' 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 appropriately sized for the tool's complexity. It front-loads the main purpose, then covers usage conditions, exclusions, and specific operational details in a structured flow. Every sentence adds meaningful information with 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?

Despite having no output schema, the description explains the return behavior (claim_token and later status read). It covers scope (Pipeworx-only), use cases, error handling guidance, rate limits, and cost—making the tool fully self-contained for an agent to decide and execute correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the claim_token usage in context ('Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and adds message guidance ('1-2 sentences typical, 2000 chars max' in schema, but description adds 'Describe the issue in terms of Pipeworx tools/packs'). This pushes it above baseline but doesn't fully compensate for all params.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature/data_gap, praise) and is distinct from sibling tools, none of which involve feedback submission.

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

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

Provides explicit guidance on when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes exclusions and alternatives, instructing users to file with a different server for non-Pipeworx tools and explaining how to disambiguate via 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds useful context: no PII, cached 5min-1h, self-aggregating, derived from CF analytics-engine. No contradictions.

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

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

Description is concise, front-loaded with purpose, and each sentence adds value. No wasted words: states function, use cases, and caching.

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 one parameter, 100% schema coverage, and no output schema, the description fully covers return format (top tools, packs, call volume) and caching behavior. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and the schema description already explains the window enum and its effect. Description adds caching detail but otherwise does not significantly enhance meaning beyond schema.

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

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

Description clearly states it returns 'top tools, top packs, and total call volume' over a window. Distinguishes from siblings like 'discover_tools' by focusing on trending/usage data.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case). Implies when not to use (e.g., for specific queries, use other 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?

Despite annotations already indicating read-only and non-destructive behavior, the description adds extensive detail on internal logic: how scanning works, semantic similarity threshold (Jaccard >= 0.30), partition filter dropping placeholder slugs, fill check against live CLOB depth, and what to do when realizable_edge_pp <= 0. This goes far beyond what annotations provide.

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

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

The description is long but well-organized with section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though it could be slightly more concise or bulleted for parameter modes. Still, it's not overly verbose given the complexity.

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

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

With no output schema provided, the description fully covers return values: opportunities array with fields, partition_check object for event mode, and fill check results. It also explains edge cases (null arb signal if placeholder fraction >20%, skipped pairs). For a multi-mode tool with algorithmic depth, this is 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?

The input schema has 100% coverage with descriptions for both parameters, but the description adds significant meaning: it explains accepted formats (full URLs for event), gives examples (e.g., 'fed-decision-may-2026'), and details how topic searches work across events. This helps the agent understand parameter usage beyond schema types.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains what each does, differentiating it from sibling Polymarket tools like polymarket_edges or 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?

The description explicitly tells when to use each mode (no args for trending scan, event for specific market, topic for cross-event scanning) and explains why you'd choose one over another, e.g., cross-event mode catches patterns single-event misses. It also warns not to trade when realizable_edge_pp ≤ 0 and references polymarket_fill_risk for custom sizing, 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?

The description extensively covers behavioral traits beyond annotations: it explains caching (1h KV cache keyed on knobs), non-destructive nature, output structure, and diagnostics. Annotations indicate readOnly, openWorld, idempotent, non-destructive, and the description aligns with and expands on these.

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

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

The description is well-structured with clear sections and bolded terms, though it is verbose. It front-loads the purpose but then provides extensive detail that, while valuable, could be more concise. The structure helps parsing, but brevity could be improved.

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 (9 parameters, no output schema), the description is remarkably complete. It covers output segments, edge calculation details, filtering logic, diagnostics for empty results, and caching behavior. No essential information is missing for an agent to use the tool effectively.

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

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

Although the input schema covers 100% of parameters with descriptions, the tool description adds significant context, such as the meaning of min_kelly and slippage_pp defaults, tradeable-edge filters, and category_filter options. This elevates the baseline from 3 to 4.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the purpose as 'what should I bet on today' and distinguishes from siblings by detailing unique model families and segments.

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

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

The description provides clear context for when to use the tool (e.g., discovering daily betting opportunities) and explains knobs for filtering. However, it does not explicitly state when not to use it or compare to alternatives like polymarket_arbitrage, though the detailed segments imply differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: snapshot TTL (60 days), decay computed from daily closes not intraday, and details about snapshot gaps. No contradictions.

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

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

The description is structured with a question, response format, and limits. It is front-loaded with purpose. A bit verbose but every sentence adds value; could be slightly trimmed but effective.

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

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

Given no output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates) and their meanings. It also covers input constraints and limitations, making the tool fully understandable without additional references.

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 defaults, max values, and meaning for 'window' (snapshot family), plus explains output structure, enhancing parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge longevity and shrinkage. It distinguishes from siblings like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides context on when to use the tool by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies but does not explicitly state alternatives or 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 read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral detail: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict flags, and warns 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 long but well-structured with bold headers for modes, making it scannable. It is front-loaded with main purpose. Some redundancy exists (e.g., repeating 'single-market' and 'basket' details), but overall it is effective. Loses one point for verbosity.

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 must explain return values. It does so comprehensively, listing all fields for both modes, including edge cases (thin legs, forced directional risk). Given the tool's complexity (two modes, four parameters), this is complete and well-covering.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters differ by mode (e.g., 'size_usd' interpretation changes for basket vs single-market) and clarifying defaults. This is helpful but not transformative.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It differentiates between single-market and basket modes, and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges, making it highly specific.

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 usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why it's needed (theoretical overround not capturable, partial basket fills lead to unhedged positions), providing clear when-to-use context.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are complemented by detailed description of behavior: two modes, response format, safety fields (compatibility_warning, temporal_alignment, skipped 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded summary. Slightly verbose but every section adds value.

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

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

Given no output schema, the description thoroughly explains return values (leg prices, top spreads, safety fields) and edge cases. No gaps for this 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 for each parameter. The description adds override logic (explicit tickers override topic) and enumerates topic shortcuts, enhancing schema meaning.

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

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

The description clearly states the tool's function as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue spreads and explains two modes (topic and explicit).

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

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

Provides explicit guidance: when to use topic mode (pre-mapped macros) vs. explicit tickers for custom pairings. Warns that pre-mapped topics often return compatibility_warning, and states that 'real cross-venue spreads are rarer.'

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. Description adds return format '{ metadata, records }' and version defaulting behavior, supplementing annotations effectively.

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 core function. No unnecessary details, each part 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 7 parameters, no output schema, and reliance on OData (external standard), the description provides essential context: what, how, where to get entities, and return shape. Could mention pagination or top/default limit (default 50 is in schema but not in description) but schema covers it.

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

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

Input schema covers all 7 parameters with descriptions (100% coverage). Description adds value by clarifying that version is optional and defaults to current verified version, which is not in schema. Beyond that, it mostly restates OData params.

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 precise verb 'query' and specifies resource 'any OpenFEMA dataset'. It distinguishes from sibling 'list_datasets' by referencing it for discovery, clarifying this tool is for actual data retrieval.

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

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

Explicitly directs users to list_datasets for available entities and filter syntax, providing clear complement. However, it does not explicitly exclude usage for datasets that may have dedicated tools (e.g., disaster_declarations), which could improve guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds scoping and pairing context but no new behavioral traits.

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

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

Three sentences, front-loaded with primary action, each sentence adds value without redundancy.

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

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

For a simple retrieval tool with no output schema, the description covers behavior, scoping, and pairing with siblings completely.

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

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

Schema coverage is 100% and the description repeats the omit-to-list-all behavior already in the schema description, adding no new semantic meaning beyond the schema.

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

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

The description clearly states the action: retrieve a value or list all keys, and it names related siblings (remember, forget) to distinguish itself.

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 when to use (lookup context stored earlier) and mentions scoping, but does not explicitly state when not to use or provide alternatives beyond 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 indicate readOnlyHint and idempotentHint, and the description adds important behavioral details: mark_read flags events read, polls are suitable, and the feed is also accessible via a separate endpoint. 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 concise (5 sentences) and front-loaded with the purpose. Each sentence adds value without redundancy, covering purpose, return fields, parameters, and alternative access.

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 read-only tool with no output schema and 5 optional parameters, the description adequately covers return fields, filtering, consumption model, and alternative access. It tells the agent what to expect and how to use it effectively.

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

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

All parameters are described in the schema (100% coverage), and the description adds context beyond the schema, such as the effect of mark_read and filtering examples. However, limit and unread_only are only briefly mentioned.

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: 'Pull fired events from your subscription feed.' It specifies the verb, resource, and scope, and distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on retrieving events from the feed.

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 guidance on when to use the tool (polls work fine) and offers an alternative method for scripts/dashboards via HTTP. However, it does not explicitly mention when not to use this tool, e.g., for subscribing or querying historical data.

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 (readOnlyHint, idempotentHint, etc.), the description details multi-source fan-out, fallback mechanisms, soft-fails, and return format, giving full behavioral insight.

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 and informative, though slightly verbose; each sentence contributes meaning, but could be tightened slightly.

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

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

Given no output schema, the description adequately explains return format and tool behavior, covering all essential aspects for an agent to use it correctly.

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

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

The description adds significant value beyond the already high-coverage schema, explaining relative shorthand for 'since', ticker/CIK options for 'value', and constraints for 'type'.

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

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

The description clearly states it provides a change feed for a company in a recent window, with specific verb phrases like 'What's new with X' and explicitly distinguishes from the sibling tool entity_profile.

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

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

Provides explicit example query phrasings and clearly states when to use entity_profile instead, offering precise usage context.

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

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

Annotations provide idempotentHint and destructiveHint. Description adds context beyond: scope by agent identifier, persistence difference between authenticated and anonymous sessions (24hr), and that it stores key-value pairs. This is valuable for the agent.

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

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

Highly concise and well-structured. Four sentences front-load the main purpose, then usage, then retention details. 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?

Given the tool's simplicity (2 required string params, no output schema), the description is complete: explains what it does, when to use, how storage works, and links to sibling tools. No gaps.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds usage examples but does not provide additional semantic meaning beyond what the schema already offers. Adequate but no extra value.

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

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

The description clearly states the verb 'Save data' and the resource 'the agent will need to reuse later'. It provides concrete examples (resolved ticker, target address, user preference) and distinguishes from sibling tools 'recall' and 'forget' by focusing on storing.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward... so you don't have to look it up again'. Also mentions pairing with recall and forget. Lacks explicit when-not to use, but 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?

Annotations already declare read-only, open-world, idempotent, non-destructive. The description goes far beyond: details cross-source enrichment (EDGAR, GLEIF, OpenFIGI), graceful degradation, explicit `unresolved` output, source labelling, and citation scheme. This is rich behavioral context that materially helps an agent predict 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 dense but efficiently structured: trigger examples, a directive, then per-type specifications with degradation and replacement notes. Every sentence adds distinct value, and the length is justified by the tool's multi-source 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 fully covers return semantics: listing resolved identifiers per type, ownership details, `unresolved` handling, and fallback behavior. It also explains internal cascade, making the tool's behavior predictable for an agent without external schema.

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

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

Schema coverage is 100%, giving baseline 3. The description adds value by specifying acceptable input variants per type (ticker/CIK/name vs brand/generic), and connecting parameter choice to output composition (e.g., FIGI only when ticker implied). This enriches what the schema itself 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 opens with concrete trigger phrases, then states a clear verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers'. It distinguishes from siblings by emphasizing ID lookup and 'Use FIRST whenever you have a name but need an ID.' This is specific and actionable.

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 directs 'Use FIRST whenever you have a name but need an ID,' establishing a clear primary use case. It also mentions replacing 2-3 manual lookups. It doesn't name alternative sibling tools, but the conditionality is enough to guide selection.

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

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

Discloses that it internally calls ai_visibility_check for each entity and returns a ranked list with score, confidence, signal density. Annotations already declare readOnly, idempotent, non-destructive, and open world; description adds context about batch behavior and ranking. No contradictions, and adds value beyond annotations.

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

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

Three sentences with clear hierarchy: purpose, mechanism, example. Front-loaded, no fluff. 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?

Covers input parameters and return values (ranked list with metrics) despite no output schema. For a composite tool, it explains internal calls and ranking. Lacks error handling or edge cases, but overall sufficient for agent selection and basic 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 has 100% description coverage, so baseline is high. Description adds meaning: 'First entry treated as the subject for narrative; rest are competitors' and clarifies default models and optional Anthropic key. This provides crucial context not in schema.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, describes the process (probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized), and gives a concrete usage example. Distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (more general).

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 case: competitive AI-marketing audits, with an example question. Implies when to use (comparing multiple entities) and treats first entity as narrative subject. However, does not explicitly state when not to use or list alternative tools, though sibling differentiation is clear enough.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: partial failures are handled gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeout. This goes 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 somewhat long but highly informative. It front-loads the composite nature and then details the output and potential issues. All sentences are necessary, but it 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 has no output schema, the description fully details the return fields. It covers all important aspects: what checks are performed, potential delays, and error handling. Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaning: scoped packages are accepted, and version defaults to latest. This provides useful context beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, bundle size, and more. It specifies the verb (scan dependency) and resource (npm package), and distinguishes from siblings by being unique and focused on npm ecosystem.

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

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

The description explicitly tells when to use the tool (when asked about safety, popularity, or cost of adding an npm package) and when not to use it (for non-npm ecosystems, which should use a different tool). This provides clear guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char limit with truncation flag. 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?

Description is well-structured with front-loaded purpose and clear details. Every sentence adds value, though slightly verbose. Still concise considering the technical detail provided.

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 output includes top-N passages with character offsets and similarity scores. Also mentions truncation flag. Parameters are fully covered. Given sibling context and annotations, the description is 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 3. Description adds meaningful context: 'text' is the document to search, 'query' is natural-language with examples, and 'limit' is max passages. Provides additional semantics beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with a specific verb 'Search Within a Source'. It distinguishes from siblings by naming ask_pipeworx_grounded and explaining the use case for large records.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and contrasts with asking about whole document. Also mentions pairing with another tool for grounded reasoning.

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 says 'Returns the new subscription id' implying each call creates a new subscription, but annotations declare idempotentHint=true, suggesting idempotency. This contradiction is not resolved. No mention of rate limits, cost, or behavior on duplicate requests. Behavioral context beyond annotations is limited.

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, starting with the main action, then requirements, types, and delivery. It is front-loaded with the key purpose. A minor deduction for length; however, the complexity justifies the detail.

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

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

Given the tool's complexity (5 types, 3 delivery channels), the description covers requirements, type-specific params, delivery behaviors, and prerequisites (e.g., SMS phone verification). Missing output schema, but the return value ('subscription id') is stated. No mention of pricing or feed retention policy, but overall adequate for a creation tool.

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

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

While schema coverage is 100%, the description adds significant value by providing detailed examples for each subscription type and delivery channel, including SMS cap, webhook signing, and JSON format. It clarifies parameter semantics beyond the schema enums and descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from siblings (e.g., list_subscriptions, unsubscribe) by focusing on creation.

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

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

The description specifies when to use the tool (create subscription) and provides context such as required Pipeworx OAuth account, supported types with examples, and delivery channel prerequisites. It does not explicitly state when not to use but gives sufficient guidance for selection.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds that it returns category-bucketed example questions with tool+argument shapes, and explains how calling without arguments vs. with topic changes output. 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?

Single paragraph is dense but well-structured, starting with purpose and then expanding. Slightly verbose with the list of categories but overall efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and behavioral context thoroughly, aided by rich annotations.

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

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

Schema coverage is 100% with a single parameter. Description adds value by listing possible topic values (finance, pharma, etc.) and explaining that omitting topic gives a cross-category spread, 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?

Description explicitly states it is an onboarding entry point, returning category-bucketed example questions. Clearly distinguishes from siblings like ask_pipeworx by being the first tool to use when the agent does not know what Pipeworx can do.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains the optional topic parameter for 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?

Annotations provide idempotentHint, destructiveHint, etc. Description adds that row is deactivated not deleted, and ownership enforced, adding valuable behavioral context beyond annotations. No contradiction.

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

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

Three concise sentences: purpose, ownership, deactivation. 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?

For a simple tool with one param and clear annotations, description covers purpose, ownership constraint, and side effects (deactivation, event retention). No output schema required.

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

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

Schema covers 100% of parameters with clear description. Description reinforces that id must be from subscribe. Ownership info is behavioral, not param-specific, but does not detract.

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

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

Description clearly states 'Cancel a subscription by id', with specific verb 'cancel' and resource 'subscription'. It distinguishes from subscribe and list_subscriptions by clarifying ownership enforcement and deactivation behavior.

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

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

Explicitly states ownership enforcement, implying when to use (your own subscriptions). Mentions that historical events remain via recent_alerts, providing context. Does not explicitly list when not to use, but is clear enough.

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

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

Beyond the annotations, the description discloses two routing paths (SEC EDGAR fast path vs. grounded pipeline), the nuanced meaning of could_not_verify vs. unsupported, and the existence of verification_error{stage,detail}. It also explains the tolerance override semantics. These are behavioral details far beyond what annotations alone 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: trigger phrases, routing logic, output contract, error caveats, and efficiency benefit. It is well-structured as a single coherent block, front-loaded with the most actionable information, and avoids 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 complex tool with no output schema, the description fully explains the return values (verdict, actual value, citation, reasoning), the special meanings of could_not_verify and unsupported, and the two pipeline paths. It gives the agent all necessary operational context to invoke the tool correctly and interpret results.

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

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

Both parameters have descriptive types in the schema, so baseline is 3. The description adds meaningful usage context for tolerance_pct (e.g., set 1–2 for hallucination detection, default implied by wording capped at 5) and clarifies the claim parameter's scope with examples. This goes beyond the schema's simple field descriptions.

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

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

The description opens with explicit trigger phrases like "fact check" and "verify the claim that…" and states a specific verb+resource: natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by describing a composite, high-level operation that replaces 4–6 sequential calls, making its scope 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?

It explicitly says "Use whenever the agent needs to check whether something a user said is factually correct," which is clear when-to-use guidance. It also differentiates handling for company-financial claims vs. other claims, but it does not mention exclusions or alternatives (e.g., when to use ask_pipeworx instead), so it misses the full 'when-not/alternatives' bar.

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