Gwas Catalog

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

Annotations already declare idempotent, read-only, non-destructive behavior. The description adds critical context: the default free model, the requirement for a BYO key for Anthropic, and the detailed return format per model (score, confidence, signals, raw_response) plus combined view. No contradictions.

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

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

The description is concise, consisting of three focused sentences. It is front-loaded with the main purpose and efficiently covers models, key usage, and return format without extraneous information.

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

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

Despite lacking an output schema, the description fully explains the return format. It covers all needed context for parameter usage, model selection, and use cases. The tool is well-documented for an agent to invoke correctly.

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

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

Schema description coverage is 100%, but the tool description adds significant meaning beyond the schema by explaining the default model, the purpose of the API key, and how context helps disambiguation. The description enriches parameter understanding.

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

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

The description clearly states it probes LLMs to score visibility (0-100) per model, specifying the exact resource and action. It differentiates from sibling tools by focusing on visibility scoring across multiple models, which is unique among the listed siblings.

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

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

The description explains use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and when to provide an API key for Anthropic. However, it does not explicitly state when not to use this tool or suggest alternatives, which would strengthen 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 and idempotent behavior, and the description adds substantial context beyond that: it reveals the tool routes to one of 5,344 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is fast. No contradictions with annotations.

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

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

The description is long but front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and then organized into rationale, examples, and escalation paths. Every sentence carries information, though some points are reiterated ('works on every tier' appears twice). Still, the structure is logical and not wasteful.

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

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

For a tool that routes to over 5,000 sources, the description is remarkably complete. It covers the types of questions, the output format (structured answer with citation URIs), fallback behaviors, and relationship to siblings. No output schema exists, so the description adequately explains return values. Complexity is high, and the description rises to it.

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

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

Schema coverage is 100% for the single 'question' parameter, so baseline is 3. The description adds meaning by providing concrete examples of valid questions ('current US unemployment rate', 'Apple's latest 10-K') and clarifying the domain (current/historical authoritative data). This helps the agent craft better queries beyond the schema's generic 'natural language' description.

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

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

The description clearly states the tool routes factual questions to authoritative data sources, fills arguments, and returns cited answers. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by naming them explicitly, and the specific verb 'routes' plus resource scope makes 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?

Explicit guidance is given on when to prefer this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also clarifies that breaking-news is handled internally, making the decision tree complete.

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

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

The description goes beyond annotations by disclosing the beta/experimental status, the live-toggle of candidate routing improvements, and the current state (no active candidate, matches ask_pipeworx exactly). It also explains that results are compared against the stable router for merge decisions and clarifies it is a fully functional router, not a fallback. This provides valuable behavioral context not present in the readOnly/idempotent/openWorld annotations.

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

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

The description is well-structured, front-loaded with the core purpose, and provides essential details about the experimental state and comparison behavior. It is somewhat verbose (e.g., the date and the 'falls back to nothing' clarification), but every sentence contributes useful context, so nothing feels wasted.

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 there is no output schema, the description compensates by referencing 'same response shape' as ask_pipeworx, which provides the missing return-value context for those familiar with the stable tool. It covers parameters via 'same arguments,' safety via annotations, and current status in detail. A slight gap is the lack of explicit guidance on what kinds of questions are suitable, but this is inherited from ask_pipeworx.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question,' so the schema already fully defines them. The description only says 'same arguments' without adding new semantic detail. Baseline 3 is appropriate because the schema carries the semantic burden and the description does not need to compensate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,344 tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing its experimental edge and candidate routing improvements. The verb 'ask' plus resource 'Pipeworx' provides a specific action and target.

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

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

The description explicitly states when to use this tool: 'when you want the newest routing.' It names the alternative 'ask_pipeworx' as the stable router, implying users should choose that for stable behavior. However, it lacks an explicit 'when not to use' statement, though this is reasonably inferred from the emphasis on experimental routing.

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, but the description adds rich behavior: it routes through 5,344 tools, returns a specific JSON shape, and includes refusal reasons like 'not_in_source' and 'data_truncated'. It also discloses the cost of one extra LLM call, providing transparency beyond annotations.

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

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

The description is front-loaded with the core purpose, then details behavior, return shape, use cases, and cost in a compact 3-sentence structure. Every sentence adds critical information without redundancy.

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

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

Despite no output schema, the description fully specifies the return format and all refusal modes. It covers routing mechanics, use cases, limitations, and cost, making it complete for a high-stakes grounded-answer tool in context of siblings.

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 contains 6 parameters all aliases for 'question' with 100% description coverage, so the schema already fully documents parameter semantics. The description does not add further parameter-level meaning, which is acceptable given high schema coverage; baseline of 3 applies.

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

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

Description clearly states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and explains it 'EXTRACTS the answer using ONLY what the tool result contains.' It also distinguishes from the sibling ask_pipeworx by noting the same routing but an extra LLM call, making it easy to select.

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 guidance: 'Use whenever an answer will be quoted, cited, or acted on...' plus when-not-to-use: 'prefer ask_pipeworx for casual lookups.' Names the alternative tool directly and provides concrete use cases (financial verdicts, legal claims).

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details behavioral traits such as: it resolves the market, classifies the bet, fans out to category-specific data packs in parallel, and returns evidence. It also covers safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread tradeability), the resolver contract (market_match_confidence, alternatives, suggestions), and resolution-rule risk (cancellation_rule parsing). This provides a comprehensive behavioral profile that helps the AI agent understand exactly what the tool does and its edge cases.

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

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

The description is lengthy but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) that aid scanning. Every sentence provides unique value, covering classifiers, fan-out examples, response shapes, safety, and cancellation rules. The front-loading of the core purpose ('Research a Polymarket bet by pulling the relevant Pipeworx data') is effective. However, the description could be slightly more concise by merging some examples; nonetheless, the structure is clear and information-dense.

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

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

Given the tool's complexity (3 parameters, no output schema, numerous edge cases), the description is exceptionally complete. It covers input formats, depth options, raw mode, classifiers, fan-out examples, response shapes (market, analysis, evidence, resolver contract, parent event, news fields), safety short-circuits, closed markets, wide spreads, and cancellation rules. The agent has all necessary context to use the tool effectively, including understanding the shape of the response despite the lack of an explicit output schema.

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

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

Schema coverage is 100% as all three parameters are documented. However, the description adds significant meaning beyond the schema: for 'market', it explains the three valid input formats (slug, URL, question text). For 'depth', it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out' and the default. For 'include_raw', it explains when to pass true (recompute deltas, cite observations, post-process) and the size implications. This extra context enables more informed 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects. The verb 'research' combined with the resource 'Polymarket bet' and the action 'pulling Pipeworx data' makes the purpose specific and unambiguous.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive guidance on when not to trust results (e.g., low-confidence resolution short-circuits, closed markets) and includes the resolver contract that agents must inspect. The fan-out examples also help agents understand which specific data sources are triggered for different bet types. This covers both when-to-use and cautionary notes.

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

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

Description adds significant behavioral context beyond annotations: detailed data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradictions with readOnlyHint etc.

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 packed with useful information but slightly lengthy. Every sentence adds value, but could be trimmed slightly for brevity while retaining clarity.

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

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

For a tool with 2 parameters and no output schema, description explains what data is returned (revenue, net income, adverse events, trials), sorting, and citation URIs, ensuring complete understanding.

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

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

Although schema coverage is 100%, description adds meaning: values for company are tickers/CIKs, for drug are names, with examples. This aids correct parameter use.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, using verbs like 'compare' and example queries. It distinguishes from siblings like 'entity_profile' by explicitly recommending over sequential lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 sequential lookups. Example uses ('which is bigger', 'rank these') make context 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?

Goes well beyond annotations by disclosing account/auth requirements, paid tier for 'thorough', latency expectations (15-60s, ~90s thorough), gap recovery behavior, contradictions[] for standard/thorough, semantic excerpting, and the guarantee that gaps are explicit and never invented. No contradiction with readOnly/openWorld/idempotent/destructive hints.

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

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

The description is long but every sentence carries distinct information, from auth to output format to latency. It is front-loaded with the most critical account requirement and sibling fallback. A more structured layout (paragraphs/bullets) would improve scannability, but the density is justified for a tool with this complexity.

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

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

Despite no output schema, the description fully explains return values (findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field) and covers auth, latency, depth semantics, and limitations. It is complete enough for an agent to select and invoke the tool correctly in varied contexts.

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

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

Schema already documents both parameters with descriptions and enum details (100% coverage). The description adds meaningful operational context beyond the schema, such as how depth levels behave (gap recovery, contradiction scan, iterative lead-chasing) and the paid requirement for 'thorough', enriching the enum semantics.

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

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

The description clearly identifies deep_research as a grounded multi-source research tool that decomposes questions into facets, routes to 5,344 tools in parallel, and returns a findings packet with evidence and citations. It explicitly distinguishes itself from ask_pipeworx and other siblings by stating it is not open-web search and is best for broad/multi-part structured-data questions.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions; for single lookups use ask_pipeworx; for breaking/colloquial current-news prefer ask_pipeworx. Also gives fallback instructions if not signed in, making alternatives and prerequisites clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly, which adds value beyond annotations.

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

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

Description is well-structured, front-loaded with purpose. Could be slightly more concise, but every sentence adds value. Length is justified by the comprehensive examples and usage guidance.

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

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

Given 6 parameters and no output schema, the description explains what the tool returns (names, descriptions, schemas, curated examples) and the calling order. Complete for discovery tool with clear 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 covers 100% of parameters with descriptions. The description mentions aliases but schema already includes that. Baseline is 3 as schema does the heavy lifting; description adds minimal extra semantic 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 uses specific verbs like 'browse, search, look up, discover' and clearly identifies the resource (tools for specific domains). It distinguishes from sibling tools by being a discovery tool rather than a domain-specific tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Lists specific scenarios like SEC filings, financials, etc., providing clear context on when to use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds concrete behavioral details: it fans across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), notes that the patents API will sunset May 2025 and will soft-fail, and explains the news fallback (GDELT→GNews). This provides useful context beyond the annotations, though some details like response size or rate limits are omitted.

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 every sentence adds value. It front-loads example triggers and a clear statement of purpose. The list of return fields could be more structured (e.g., bullet points), but it is still efficient and not overly verbose.

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

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

Given no output schema and high complexity (multiple data sources), the description does a good job covering the main return fields: CIK, filings with URIs, fundamentals sorted by period_end, patents status, news fallback, and LEI. It also addresses edge cases like patents sunset and name resolution. However, it could mention if there are limits on news counts or pagination.

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

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

Schema coverage is 100% (both parameters described). The description adds extra meaning: it explains that type is 'company' only and mentions 'person/place coming soon', and for value it gives examples of ticker and CIK formats ('AAPL', '0000320193') and reiterates that names are not supported. This adds value 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 purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides concrete example queries and lists the returned data types (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from chaining single-pack lookups and from sibling tools like resolve_entity and compare_entities.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clearly states when not to use it: 'names not supported (use resolve_entity first if you only have a name).' This provides excellent guidance on when to use this tool versus 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, idempotentHint=true. Description adds no new behavioral traits beyond the 'Delete' action and 'clear sensitive data' context, which is more usage-related.

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

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

Two concise sentences: first states purpose, second adds usage guidelines. No filler.

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

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

Given simple tool with one parameter, full schema coverage, and annotations, description is complete. Could mention return value or confirmation, but not necessary.

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

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

Schema coverage is 100% for the single 'key' parameter with description 'Memory key to delete'. Description adds no additional 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?

Clears purpose: 'Delete a previously stored memory by key.' Verb 'Delete', resource 'memory', scope 'by key'. Distinguishes from siblings '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?

Explicit guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data... Pair with remember and recall.' Tells when and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that it fetches the page, extracts title/description/key links, and emits standard format. No contradictions.

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

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

The description is concise: two sentences defining the action and one sentence listing use cases. It is front-loaded with the core purpose, no unnecessary words.

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

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

Given the tool's complexity and rich annotations, the description covers purpose, output format, and use cases adequately. Lacks details on error handling or edge cases, but is sufficient for an AI agent to invoke correctly.

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

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

Schema coverage is 100% with both parameters described. The description does not add significant extra meaning beyond the schema, such as format constraints or error handling, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the output format and use cases. It differentiates itself from siblings like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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

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

The description explicitly lists three use cases (indexing client site, drafting for own project, auditing competitor) providing clear when-to-use guidance. However, it does not explicitly state when not to use or name alternatives, though siblings imply other scanning tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=true. The description adds source (EBI/NHGRI) and keyless access, which provides some behavioral context but does not significantly extend beyond the annotations.

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

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

Two sentences with no fluff. Front-loaded with tool name and source, then details. Every word serves a purpose.

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

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

For a simple lookup tool with rich annotations and a single parameter, the description covers source, keyless access, and output content. Missing details on output format or error cases, but acceptable given annotations and 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% with a single parameter 'rsid' well-documented in the schema (type, description, example). The description repeats 'by rsID' but adds no extra semantic detail beyond the schema.

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

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

Description clearly states it looks up a SNP by rsID from the GWAS Catalog, specifying the data returned (functional class, location, mapped genes). The verb 'look up' and resource 'SNP' are precise, and the context 'GWAS Catalog' distinguishes it from generic SNP retrieval tools.

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

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

No explicit guidance on when to use this tool versus alternatives like 'snp_associations'. The description mentions 'keyless' but does not address prerequisites, limitations, or scenarios where another tool would be preferred.

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 convey readOnly, idempotent, and non-destructive nature. The description adds that it returns specific fields and defaults to active subscriptions only, but no behavioral traits beyond what annotations provide. No contradiction.

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

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

The description is two sentences with no wasted words. It front-loads the purpose and provides actionable guidance in the second sentence.

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 optional parameter, no output schema, and rich annotations, the description covers all necessary context: what it does, what it returns, and a typical use case. It is fully sufficient for an agent to use this tool correctly.

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

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

Schema coverage is 100% for the single parameter 'include_inactive', which is well-described in the schema. The description does not add information about this parameter, so it adds no value beyond the schema.

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

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

The description clearly states the verb 'List' and the resource 'caller's active subscriptions', and lists the return fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by specifying it is for reviewing current 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 explicitly advises when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context for appropriate usage, though it could contrast with alternatives more directly.

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

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

Beyond annotations, description discloses it's free, doesn't count against tool-call quota, and rate-limited to 5 per identifier per day. 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?

Six well-structured sentences, front-loaded with purpose. Could trim 'Describe the issue in terms of Pipeworx tools/packs' 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 feedback tool with complete schema and annotations, description is thorough. No output schema needed; context signals fully addressed.

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

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

Schema coverage 100%; description adds usage context for type enum, message specifics, and context object. Slightly redundant with schema but adds clarity.

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 sends feedback to Pipeworx team for bugs, features, data gaps, or praise. Distinguished from sibling tools (research/query tools) by being a feedback channel.

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 (bug, feature, data_gap, praise) and what not to do (don't paste user prompt). Includes rate limit and quota info.

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 valuable context: data source (CF analytics-engine), no PII, cached (5min-1h). This goes well 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 concise (four sentences), well-structured: purpose first, then use cases, then technical details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional parameter, no required output schema), the description is fully complete. It explains return values, data source, privacy, and caching. No gaps remain.

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

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

The single parameter 'window' has 100% schema coverage with enum and description. The description reinforces effective use (short vs long windows) and adds meaning about what each window reveals. Baseline is 3; the additional guidance raises it 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 returns trending agent usage data: top tools, top packs, and total call volume. It specifies the resource (Pipeworx trending data) and distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregated agent call activity.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment) and explains how to choose between windows (short for hotness, long for steady-state). While it doesn't explicitly state when not to use it or list alternative tools, the context is clear enough for an agent.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds critical behavior: partition filter drops placeholder slugs, semantic anchor requires Jaccard similarity ≥0.30, and fill check against live CLOB depth. 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?

While lengthy, every sentence adds value. Front-loaded with main purpose, then logically breaks down modes and details. Slightly verbose but well-structured for complex tool.

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

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

Comprehensive: explains multiple modes, edge cases (placeholder slugs, low similarity), output structure (opportunities, partition_check, fill check), and references sibling tool for custom sizing. No output schema, so description adequately covers return values.

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

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

Schema has 100% coverage with descriptions for both 'event' and 'topic'. Description significantly enriches by explaining exact usage (e.g., event slug format, topic seed question example) and provides behavioral details 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?

The description explicitly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes between three modes (no args, event, topic). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique functionality.

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?

Clear guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also advises when not to trade (realizable_edge_pp <= 0) and mentions polymarket_fill_risk for custom sizing.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: caching (1h at KV level), model details, slippage assumptions, Kelly sizing, 24h move warning, and reliability notes on Fed bets. This goes well 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 quite verbose with detailed model explanations but well-structured: purpose first, then segments, knobs, response. It front-loads key info. Some technical details could be trimmed for conciseness without losing clarity.

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

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

With 9 parameters and no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), caching, and edge attributes. It covers all aspects a user needs to understand tool usage and outputs.

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

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

Despite 100% schema coverage, the description adds significant context to each parameter, e.g., min_kelly explains it skips opportunities too small to bet, min_partition_leg_kelly clarifies why min_kelly doesn't apply to partition arbs, slippage_pp explains Polymarket fees and typical spreads. This enhances understanding beyond schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on discovery without paging hundreds of markets, and provides detailed model family breakdown.

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

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

The description explicitly states the use case (betting opportunities) and provides guidance on knobs like min_liquidity and max_spread_pp. However, it does not directly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity on when to prefer this tool over others.

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 hints. The description adds significant context: data comes from daily snapshots, bounded by 60-day TTL, provides time-series, trend classification, decay calculation from daily closes (not intraday), and response structure. 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 block but well-structured: starts with core purpose, then details response fields (tracked[], expired[], snapshot_dates[]) with clear labels. While somewhat verbose, every sentence adds value. Could be slightly more concise, but overall 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?

With no output schema, the description fully explains all return fields (tracked, expired, snapshot_dates) and their subfields (trend, decay, first_seen, lifespan_days, etc.). Also covers limitations (60-day TTL, snapshot start, intraday vs. daily). Complete for a complex tool.

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

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

The input schema has 100% coverage with descriptions of both parameters (days, window). The description adds value by specifying default values (14, '1wk'), clamp range (2-30), and listing window family options ('24hr | 1wk | 1mo'), enhancing usability beyond the schema alone.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by focusing on persistence/decay telemetry rather than raw edges.

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

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

The description implies usage for assessing edge quality over time (e.g., distinguishing fresh vs. old wide edges) but does not explicitly state when to use or not use this tool versus alternatives like polymarket_edges. No clear when-not-to-use guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description, which adds behavioral details like walking the ladder, returning verdict (clean|degraded|cannot_fill), and warning about forced directional risk. 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 dense and informative, but could benefit from better structure (e.g., bullet points for modes) to improve readability. However, every sentence is valuable and front-loaded with key 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?

Despite no output schema, the description fully specifies return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and covers edge cases like thin_legs and forced_directional_risk. Complete for a risk-check tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema. For example, it explains size_usd in basket mode as 'settlement notional S — shares per leg' and clarifies default side logic for baskets. This enhances the schema's documentation.

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 distinguishes between single-market and basket modes, providing specific verb+resource and differentiating from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial basket fills converting an arb into unhedged directional position, indicating 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?

Disclosures beyond annotations: explains safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), how spreads are computed, and when they are meaningless. No contradiction with readOnly/openWorld/idempotent 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 (modes, response fields, safety warnings), but slightly verbose with some redundant phrasing (e.g., 'Real cross-venue spreads are rarer...' could be shorter). Still, every sentence adds value.

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

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

Given the complexity (3 optional params, no output schema), the description comprehensively explains return values, safety fields, and interpretation of edge cases (compatibility warnings, temporal misalignment). No missing details.

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

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

Even though schema coverage is 100%, the description adds significant context: explains the purpose of each mode, how parameters interact (override behavior), and what each parameter maps to. This enriches understanding beyond the schema's simple descriptions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question, distinguishing it from sibling arbitrage tools. The verb 'Cross-venue spread' and resource specification are specific and unambiguous.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers) with concrete examples. Provides when-to-use guidance ('pre-mapped shortcuts' vs 'custom pairings') and warns that most pre-mapped topics return compatibility warnings, guiding realistic expectations.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable context: scoped to identifier (anonymous IP, BYO key hash, or account ID). 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 three sentences, front-loaded with the purpose, and every sentence adds value. No waste and clearly structured.

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

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

Given the simplicity of the tool (one optional param, no output schema), the description fully covers functionality, use case, and scope. Nothing missing.

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

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

Input schema has 100% coverage for the single 'key' parameter. Description adds that omitting key lists all keys, which matches schema explanation. No additional depth needed, baseline 3 is appropriate.

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

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

Description clearly states verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings by mentioning 'remember' and 'forget'. It covers both functions of recalling a specific key or listing all keys.

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

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

Description provides explicit use case: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget. Missing explicit when-not-to-use, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that mark_read can flag events read, which is a state change but idempotent. Consistent with annotations; no new behavioral traits beyond what annotations imply.

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 main action and return details. No redundant text. Every sentence adds value.

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

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

No output schema, but description explains what each alert carries (source, citation_uri, raw payload). Covers all parameters except unread_only implicitly. Mentions polling and alternative HTTP endpoint. Could include response format details, but sufficient.

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

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

Schema coverage is 100%, but description adds value by explaining mark_read's effect (next call shows newer ones) and giving an example for type ('sec_8k'). 'unread_only' not explicitly described, but schema covers it. Baseline 3 plus extra for context on mark_read.

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 'pull' and specific resource 'fired events from your subscription feed'. Distinguishes from sibling tools like list_subscriptions and subscribe by detailing what data is returned (source, citation_uri, raw payload).

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

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

Provides guidance on filtering by type and since, using mark_read to manage read state, and mentions polling suitability. Provides alternative HTTP endpoint for scripts/dashboards. Lacks explicit 'when not to use', but context is clear.

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

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

The description adds significant context beyond annotations, including fan-out to multiple sources, fallback logic, soft-fail for USPTO, and return structure (changes[] with URIs). No contradictions with annotations.

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

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

The description is well-structured and front-loaded but slightly lengthy due to detailed explanations of sources and fallback. It could be more concise while retaining key information.

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

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

Given the complexity (multiple sources, fallback, soft-fail, three required parameters) and no output schema, the description covers all aspects: purpose, parameters, sources, fallback, return type, and alternatives without gaps.

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

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

The description adds practical guidance beyond the schema: type is limited to 'company', value accepts ticker or CIK, and since includes relative date shorthand with recommended typical values. Schema coverage is 100%.

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

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

The description clearly states the tool provides a change feed for a company in a recent time window, specifying sources (SEC, GDELT, USPTO) and distinguishing from the sibling entity_profile tool.

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

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

The description provides example queries and explicitly recommends an alternative (entity_profile) when a static profile is needed. It also explains fallback behavior (GDELT to GNews) and soft-fails for USPTO.

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 important behaviors beyond annotations: memory is scoped by user identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. Annotations indicate idempotentHint=true, which description does not contradict.

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

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

Concise and well-structured: purpose statement, usage guidance, behavioral details, and pairing with other tools. No extraneous information.

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

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

Fully covers the tool's functionality for its complexity. With only two simple params and no output schema (write operation), the description provides all necessary context: when, what, how long stored.

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

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

Schema description coverage is 100%. The description adds value by suggesting key naming conventions (e.g., 'subject_property', 'target_ticker'), which enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides specific examples (resolved ticker, target address, user preference, research subject) and distinguishes from siblings like recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget for retrieval and deletion, providing clear context for usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that each call 'cascades through several lookup endpoints internally', providing useful behavioral context beyond the annotations.

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

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

The description is three sentences: examples, usage directive, and type details. It is well-structured, front-loaded, and every sentence adds value with no redundancy.

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

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

No output schema exists, so the description covers return values for both types, includes citation URIs, and mentions internal cascading. For a simple 2-parameter tool, 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?

Schema coverage is 100% with detailed descriptions, but the description adds meaning by explaining what each type returns (ticker + CIK + citation for company; RxCUI + ingredient + citation for drug) and acceptable input formats.

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 examples ('What's the ticker for...') and clearly states the tool resolves names to canonical identifiers. It distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID resolution.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It does not explicitly state when not to use, but the context is strong enough.

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

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

The description adds significant context beyond annotations: it explains the workflow (probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized), the return structure (ranked list with score, confidence, signal density), and the treatment of the first entity as the 'subject'. 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?

Three sentences, front-loaded with the main purpose, no unnecessary words. Every sentence adds value.

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

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

Despite no output schema, the description clearly states what the tool returns (ranked list with score, confidence, signal density). For the given complexity and parameters, this 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%, so the baseline is 3. The description adds value by explaining the entities array ordering (first is subject) and the default model, which goes beyond the schema.

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

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

The description uses specific verbs ('Compare', 'Probes', 'Ranks') and nouns ('AI visibility', 'entities'), clearly distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, but it does not explicitly state when to use this tool versus siblings like compare_entities.

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 behavioral details: fans out across two services, potential 5-30s delay for Bundlephobia first measurement, partial failures degrade gracefully with sources_failed listed.

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 with two well-structured sentences. It front-loads the key purpose and then provides necessary detail without redundancy.

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

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

Despite no output schema, the description fully explains the return format (summary block, advisory details, links, alternative versions) and behavior under partial failures. It also specifies ecosystem scope and graceful degradation.

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 enhances parameter understanding by explaining how the parameters are used (fans out to deps.dev and bundlephobia) and mentions the default behavior for version, which aligns with 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 does a composite check for npm packages, combining data from deps.dev and bundlephobia, using the verb 'scan' and resource 'dependency'. It distinguishes itself from sibling tools by specifying its unique functionality and scope.

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

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

The description explicitly states when to use the tool (questions about safety, popularity, size, cost) and provides exclusion criteria (NPM ecosystem only in v1, other ecosystems handled differently).

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), the description adds crucial behavioral details: truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping), cosine similarity, and return structure (passages with offsets and scores). 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?

Four sentences, front-loaded with purpose. Each sentence adds unique value: purpose, use case, pairing, and technical details. No redundancy or 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?

Despite no output schema, the description explains return format (top-N passages with character offsets and similarity scores), limits (200K chars with truncation flag), and parameter constraints. All essential information is covered.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description reinforces usage but does not add significant new semantic meaning beyond what the input schema already provides.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and provides specific examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and the context of avoiding large prompts.

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: 'Use when the record is too big to cram into the prompt'. Also specifies what to pair with (ask_pipeworx_grounded) and the benefit of saving context and returning verifiable passages.

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, open-world, idempotent, and non-destructive. The description adds value by specifying the source (EBI/NHGRI) and keyless access, as well as the specific fields returned (risk allele, p-value, etc.), providing behavioral context 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?

Single sentence that is front-loaded with the core purpose and key details. No redundant or unnecessary information; every phrase contributes to understanding.

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?

Tool has only two simple parameters, no output schema, and rich annotations covering safety and idempotency. The description sufficiently explains what the tool returns and its source, making it complete for an agent to use. Minor gap: no mention of pagination or error handling, but overall adequate.

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

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

Schema coverage is 100% with descriptions for both rsid and limit. The description does not add new parameter details beyond what the schema provides, so baseline score of 3 is appropriate. The description does mention rsID and limit implicitly but no extra semantics.

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

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

Description clearly states it retrieves trait/disease associations for a SNP from the GWAS Catalog, listing specific fields (risk allele, p-value, etc.) and the data source. It differentiates from siblings like get_snp and studies_by_trait by specifying the focus on associations with detailed effect sizes.

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

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

Description mentions 'Keyless, from EBI/NHGRI' and provides examples, but lacks explicit guidance on when to use versus alternatives like get_snp or studies_by_trait. No when-not or exclusionary context is provided.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying return fields (accession, PubMed ID, etc.), that it is keyless, and the data source (EBI/NHGRI). This goes beyond annotations but does not cover all edge cases (e.g., pagination).

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. Every sentence adds value: first for what it does, second for return fields and source. 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?

For a simple list-returning tool with good annotations and schema, the description is quite complete. It lists return fields, notes keyless access, and mentions the data source. The absence of pagination details is a minor gap, but overall adequate.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only noting that trait is an EFO term. The schema already provides examples 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 finds genome-wide association studies for a specific disease/trait, using the GWAS Catalog. It distinguishes from sibling tools like 'get_snp' and 'snp_associations' by focusing on studies by trait, and the name itself reinforces the purpose.

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 (to find studies for a given trait), but does not explicitly state when not to use it or mention alternative tools. However, the context is sufficient for an AI agent to infer appropriate usage.

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

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

Annotations indicate idempotent, non-destructive, open-world. The description adds details: OAuth requirement, phone verification, SMS cap (10/day), webhook auto-disable after 10 failures, and that the webhook secret is returned only once. No contradiction with annotations.

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

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

The description is thorough but somewhat lengthy. It front-loads the primary purpose and then expands into details. Every sentence adds value, but minor redundancy could be trimmed (e.g., phone verification is mentioned twice).

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

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

Given the complexity (3 parameters, nested objects, 5 enum types, multiple delivery options) and no output schema, the description is comprehensive. It covers prerequisites, type-specific parameters, delivery channel behavior, limits, and return value (subscription id).

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 substantially enriches parameter meaning with examples (e.g., items codes for sec_8k, topics for polymarket_edge, required fields for patent_grant). Delivery channels are explained in detail beyond schema descriptions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

It specifies prerequisites (Pipeworx OAuth account), supported event types, and delivery channels. It also mentions that anonymous/BYO cannot persist subscriptions, giving a clear when-not-to-use. However, it does not directly compare to closely related tools like 'recent_alerts' or 'polymarket_arbitrage'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining the output structure (category-bucketed questions with tool+argument shapes) and that it draws from a live catalog, which goes beyond annotation scope.

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

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

The description is front-loaded with synonyms and purpose, uses bullet-like structure for categories, and each sentence contributes value. Slightly verbose but well-organized; no wasted words.

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

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

For a tool with no output schema, the description fully describes the return value: category-bucketed example questions with tool details. It covers usage, parameter behavior, and the context of being an onboarding entry point, leaving no major gaps.

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

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

Schema coverage is 100%, and the description elaborates on the topic parameter: lists specific focus areas ('finance', 'pharma', etc.), explains that omitting gives a cross-category spread, and connects to the overall 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 returns category-bucketed example questions for onboarding new users, using specific verbs like 'returns' and 'call'. It distinguishes from siblings by being the first tool to use when learning about Pipeworx's capabilities.

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 to 'use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to focus with a topic parameter. This provides clear when-to-use guidance and contextual 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds key behavioral details: the row is deactivated, not deleted, so historical events remain via recent_alerts. 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?

Three concise sentences with no wasted words. Front-loaded with the main action, followed by constraints and side effects.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, deactivation behavior, and impact on historical data. It is fully complete.

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

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

Schema coverage is 100% with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional semantic meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool cancels a subscription by ID. The title 'Unsubscribe from Alerts' and verb 'Cancel' make the purpose explicit, and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use and when not. It does not mention alternatives but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant value by detailing the two processing paths, tolerance parameter behavior, and return components (verdict, actual value with citation, reasoning). No contradictions with annotations.

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

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

The description is front-loaded with trigger phrases and uses bullet-like examples. It is comprehensive but slightly verbose; every sentence contributes value (explaining paths, replacements, returns), so it earns its length while remaining clear.

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

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

Given the tool's complexity (two claim types, tolerance, no output schema), the description is complete: it covers processing, fallback, return components (verdict, value, citation, reasoning), and parameter overrides. No essential details are missing for an AI agent to correctly select and invoke it.

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

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

Schema coverage is 100% with both parameters described. The description adds practical nuance: tolerance_pct can override implied wording (e.g., set 1-2 for hallucination detection) and default cap at 5%. This enhances understanding beyond the schema's static description.

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

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

The description clearly defines the tool's purpose as claim verification/fact-checking with specific trigger phrases. It distinguishes between company-financial claims (processed via structured SEC EDGAR + XBRL) and other claims (grounded pipeline), which differentiates it from any sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two processing paths. While it lacks explicit 'do not use when' guidance, the context is clear and it mentions replacing 4-6 sequential calls, implying efficiency benefits.

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