Dryad

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

Annotations already convey safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: the default model is free, Anthropic requires a BYO key with direct billing, and the return format includes per-model fields. No contradictions.

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

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

The description is very concise (two sentences), front-loads the action and output, and uses clear, direct language. Every sentence adds essential 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 having no output schema, the description sufficiently describes return values (per-model score, confidence, signals, raw_response + combined view). Use cases are provided. Minor gaps: no mention of pagination or rate limits, but overall complete for a non-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?

Schema descriptions cover all parameters (100% coverage), so baseline is 3. The description does not add significant meaning beyond stating the default model and the role of _apiKey, which is already implied in the schema. Minimal added value.

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

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

The description clearly specifies the verb 'probe' and the resource 'LLMs', details the output as a visibility score (0-100) per model, and lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This makes the tool's purpose distinct and actionable.

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

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

The description provides explicit contexts for use (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, it does not guide when to avoid this tool or suggest appropriate sibling alternatives like 'scan_competitor_ai_presence' for competitor-specific checks.

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

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

The annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive) already carry the safety profile, lowering the bar. The description adds real value beyond them by disclosing the internal behavior: it routes to one of 5,743 tools, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. No failure modes or limitations are disclosed, but for a read-only single-question tool the disclosed behavior is sufficient and consistent with 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 front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), followed by scope, mechanism, trigger phrases, and examples in a sensible order. At roughly 200 words it is long but mostly earns its length through concrete domains and examples; however, the same preference is stated three times ('PREFER OVER WEB SEARCH', 'even if web search could also answer it', 'START HERE for most questions') and the dangling em dash at the end suggests an awkward truncation.

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 only one required parameter and no output schema, the description covers everything an agent needs: when to invoke it, what to pass, what happens internally, and what the response looks like (structured answer with stable pipeworx:// citation URIs). The explicit mention of the citation format is especially valuable given the missing output schema. The only gap, differentiation among the ask_pipeworx variants, is minor for such a simple invocation contract.

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 individually described, so the baseline is 3. The description adds meaning on top by defining what makes a good value for the question parameter — factual, current or historical, real-world entities/events/numbers — and by giving six concrete example questions an agent can pattern-match against. The alias parameters (q, text, input, query, prompt) are correctly left to 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?

States an unmistakable function: a natural-language router that selects from 5,743 tools across 1,500 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. The domain list (SEC filings, FDA drug data, FRED/BLS, USPTO patents, weather, clinical trials, news, etc.) plus six concrete example queries make the scope specific and testable. It is clearly positioned as the default tool for factual questions, distinct from web search and from domain-specific 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?

Provides explicit trigger conditions ('Use whenever the user asks "what is", "look up", "find", "get the latest", "how much", "current"') and an explicit override of the main alternative: 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it'. However, it never names sibling alternatives such as ask_pipeworx_grounded, ask_pipeworx_beta, or deep_research, so an agent gets no guidance for choosing among the near-twin variants on the sibling list.

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 the annotations (readOnly=true, openWorld=true, idempotent=true, destructive=false) by disclosing the live candidate-retirement cycle, the current inactive state ('the last was retired on outcome evidence 2026-07-26'), and the crucial clarification that it 'falls back to nothing — this IS a full working router.' It also reveals the evaluation loop where outputs are compared to decide merges. This is unusually candid and contradicts nothing in the annotations.

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

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

Four dense sentences, each earning its place: identity/scope, current state, usage directive, and behavioral clarification. The defining trait is front-loaded in the first clause. Slightly long, but the length correlates with genuinely useful content rather than padding.

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

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

For a single-required-parameter router with rich annotations and no output schema, the description covers the essentials: what it is, how it differs from siblings, current runtime state, usage, and expected response shape ('same response shape' as ask_pipeworx). Nothing an agent needs to call it correctly is missing; the only gap is that behavior when a candidate IS active is described generically, not concretely.

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

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

Schema description coverage is 100% — all six parameters (q, text, input, query, prompt, question) are individually documented as aliases for the required 'question' field. The description adds only the compatibility note 'same arguments' as ask_pipeworx, which is marginal beyond the schema. At high schema coverage the baseline of 3 is appropriate.

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

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

The description states a clear purpose: this is a beta version of ask_pipeworx, an 'identical universal router' with the same 5,743 tools, arguments, and response shape. It distinguishes itself from the stable sibling (ask_pipeworx) and the grounded variant (ask_pipeworx_grounded) by being the experimental edge. It relies slightly on knowing what ask_pipeworx does, but 'universal router' plus the tool count conveys the core function directly.

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

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

Provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the stable alternative and the condition selecting this tool, and clarifies that results are compared against the stable router. It stops short of an explicit when-not-to-use statement, but 'experimental edge' and the beta naming imply the stable tool is the safer default.

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

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

The description discloses the refusal contract with specific refusal_reason enums (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the exact success payload shape. It also adds behavioral context beyond the annotations: it costs an extra LLM call, refuses when data doesn't directly answer, and is designed for high-stakes reads. Annotations are not contradicted; readOnlyHint and idempotentHint align with a read/extract operation.

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

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

The description is dense but every sentence carries load-bearing information: mode, capability, data flow, return contract, refusal reasons, use cases, cost tradeoff, and preference guidance. It is front-loaded with the most important differentiator (hallucination-resistant) and ends with actionable routing advice. 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 6 schema aliases and a rich behavioral contract, the description fully covers the decision space: what it does, how it differs from ask_pipeworx, when to use it, what it returns on success, what refusal reasons exist, and the cost consequence. The absence of an output schema is compensated by the explicit return shape in the description. An agent has everything needed to invoke and interpret 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% and the schema already documents the question parameter plus aliases. The description adds context about what the question is used for (routing, filling arguments, fetching data) and that the output is grounded/extracted from tool results, which gives the parameter semantic weight beyond 'a question string.' However, it doesn't discuss question format beyond natural language, which the schema already covers.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that retrieves data and extracts answers only from tool results. It specifies the exact verb ('extracts'), the resource (tool results across 5,743 tools/1,500 sources), and distinguishes it from ask_pipeworx in the first sentence. The contrast is explicit: same routing, but grounded extraction with refusal behavior.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on... financial verdicts, legal claims, medical lookups, public statements') and when not to ('prefer ask_pipeworx for casual lookups'). It also references the sibling tool ask_pipeworx by name and explains the cost tradeoff (one extra LLM call), which is clear decision 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?

The description extensively discloses behaviors beyond annotations: fan-out logic, resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed/dead market handling), wide-spread market warnings, and resolution-rule risk parsing. It aligns with annotations (readOnly, openWorld, idempotent, non-destructive), adding rich context.

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

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

The description is front-loaded with the main purpose, and uses clear section headers (e.g., RESPONSE SHAPES, RESOLVER CONTRACT) for complex details. While lengthy, the verbosity is justified by the tool's complexity. Could be trimmed slightly, but remains well-organized and accessible.

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 (market resolution, classification, fan-out, safety checks, risk parsing) and lack of an output schema, the description covers all necessary aspects comprehensively. It explains response shapes, edge cases, and failure modes, making it complete for effective use by an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter's flexibility (slug, URL, question text) and providing examples. It also contextualizes the depth parameter through fan-out examples and explains the include_raw parameter's effect on response size. This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet, comparison). The use cases ('should I bet on X', etc.) differentiate it from sibling tools like polymarket_edges, which likely provide edge lists rather than single-bet research.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or direct alternatives from the sibling list, so it lacks explicit exclusions.

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

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

The description discloses behavioral traits beyond annotations: e.g., it pulls LATEST 10-K data for companies (handling off-calendar fiscal years), FAERS data for drugs, sorts results by primary metric, and returns citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint, 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?

The description is well-structured with examples, separate handling of type, and front-loaded key guidance. Every sentence adds value (e.g., 'Replaces 8–15 sequential lookups'), and it remains focused 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?

Given no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers both entity types comprehensively, making the tool fully understandable for an AI agent.

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

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

With 100% schema coverage, the description adds value by explaining the type parameter's data scope (e.g., company: SEC EDGAR/XBRL; drug: FAERS) and providing concrete examples for values (tickers for company, drug names). It clarifies the max/min constraints already in schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with explicit example queries like 'compare X and Y' and 'which is bigger'. It distinguishes from sibling tools by advising 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description provides explicit when-to-use guidance (head-to-head comparisons, rankings) and warns against sequential lookups. It details context for company vs drug data, including specific data sources and metrics, ensuring appropriate selection.

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

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

Beyond the annotations, the description discloses account/plan requirements, expected latency (15-60s, up to ~90s for thorough), the gaps[] array for unanswered facets, contradictions[] for standard/thorough, fetchable citation_uri semantics, semantic excerpting of large records, and a 'never invented' guarantee. This is far richer than the readOnlyHint/idempotentHint annotations alone.

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

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

The description is long but every sentence carries distinct decision-relevant information. It is front-loaded with the account requirement and routing alternative, then flows through purpose, usage, depth behavior, output details, and latency. The structure mirrors the mental model an agent needs before invoking the tool.

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

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

With no output schema, the description fully specifies the findings packet shape: verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop, and citation_uri. It also covers latency, prerequisites, and grounding constraints, so nothing essential for correct invocation or result interpretation is 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?

Although schema coverage is 100%, the description adds substantial meaning to the depth parameter: quick=3 single-hop, standard=3 with gap-recovery and contradiction scan, thorough=6 paid with iterative lead-chasing. It also clarifies that broad/multi-part questions are acceptable because decomposition is the core behavior.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' and explains exactly how it works: decomposes into facets, routes to tools in parallel, returns a findings packet. It explicitly differentiates from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx as the single-lookup alternative.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and clear when-not-to-use instructions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also flags the paid prerequisite for the thorough depth and the distinction from open-web search.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly. No contradictions.

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

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

Two sentences, front-loaded with purpose, then usage guidance. Every sentence provides essential information with no waste.

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, many siblings, and no output schema, the description fully covers return format, usage context, and when to call. Complete for a discovery tool.

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

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

Schema coverage is 100% with all 6 parameters described. The description mentions aliases but adds little beyond schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, FDA drugs, etc.), clearly distinguishing it from sibling tools which are specific data operations.

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).' This gives clear when-to-use guidance and implies alternatives.

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

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

The description goes well beyond the annotations by disclosing parallel fan-out across sources, the semantics of sources_used/sources_failed, that empty sections mean real 'no data' not a bug, name resolution behavior, private company handling, and fallback behavior like GDELT→GNews. This provides rich behavioral context that annotations alone do not convey. No contradiction with annotations exists.

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 query examples and a strong preference rule. It is dense but mostly information-bearing, covering inputs, outputs, sources, and edge cases. It loses a point for being a long single unstructured paragraph with some redundancy with the schema's parameter descriptions.

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 carries full responsibility for explaining what the tool returns. It details each data source, output sections, resolved identities, source success/failure reporting, and input variations. An agent has enough context to invoke the tool correctly and interpret results across many edge cases.

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 meaningful value by giving concrete examples, explaining that 'company' and 'ticker' are interchangeable, noting that names resolve via SEC EDGAR, and addressing the private-company resolution case. It slightly repeats schema content but still 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 a specific verb and resource: building a full cross-source profile of a US public company in one parallel call, with multiple query examples. It is easy to distinguish from siblings like compare_entities or resolve_entity because it explicitly targets a holistic single-company profile.

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

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

The description explicitly says to ALWAYS PREFER this tool over chaining single-pack lookups when the user asks for a holistic view. It also clarifies acceptable inputs and edge cases like private companies. However, it does not name specific sibling alternatives or state explicit when-not-to-use conditions, so it falls just short of full 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 destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not detail edge cases like missing keys. No contradiction.

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

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

Two concise sentences with zero waste. Front-loaded with the action and 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 tool with one parameter and no output schema, the description fully covers when, what, and with which siblings. No gaps remain.

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

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

Schema coverage is 100% with a clear description 'Memory key to delete.' The description adds 'by key' but no new semantic 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 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember and recall'.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds behavioral context (fetches page, extracts info, emits text) without contradicting annotations.

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

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

The description is a single paragraph of ~60 words, front-loading the main purpose and covering output format and use cases. Every sentence earns its place without redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description fully covers functionality, output format, and usage contexts. Annotations provide additional safety info. No gaps.

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

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

Schema coverage is 100%, with both parameters described. The description adds context about max_links defaults (25) and max (50) but does not provide significant additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the process (fetches page, extracts title/description/key links) and output format (standard markdown). This distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases (getting client site indexed, drafting own llms.txt, auditing competitors). It provides clear contexts but does not mention when not to use the tool or name alternative tools, which would strengthen the guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'Keyless' (no authentication) and details the returned fields, 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?

Two concise sentences: first defines purpose and input, second describes output. 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?

Given the simple tool with one parameter, strong annotations, and a clear description of return values, the description is complete enough for an agent to understand behavior and output without an 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% and already describes the DOI parameter. The description adds specific examples and clarifies the optional 'doi:' prefix, adding marginal value beyond the schema.

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

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

The description clearly states the tool fetches a single Dryad dataset by DOI, returning full metadata and a download URL. It distinguishes from sibling tools like 'search_datasets' which would be for querying multiple datasets.

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

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

The description implies usage for fetching a specific dataset by DOI, and mentions 'Keyless' indicating no auth needed. It does not explicitly state when not to use or recommend alternatives, but the sibling list includes search_datasets for broader searches.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns specific fields and lists active subscriptions by default, but does not mention pagination or rate limits. This is adequate given the tool's simplicity.

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, front-loaded with purpose, and contains no unnecessary words. It efficiently communicates what the tool does and when to use it.

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

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

The description provides a complete summary of the return fields (id, type, params, created_at, last_fired_at, fire_count) and usage context, compensating for the lack of an output schema. The tool is simple with one optional parameter, so the description covers all needed context.

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

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

Schema coverage is 100% with a clear description for the single parameter 'include_inactive'. The tool description does not add additional parameter semantics beyond what the schema provides, so baseline score 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 'List the caller's active subscriptions' with a specific verb and resource. It lists the returned fields and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

Explicitly states 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use guidance and implies when not to use (e.g., when subscribing or unsubscribing).

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

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

Annotations are all false, so the description carries the burden. It richly discloses side effects: report is read daily, rate limit (5/day/identifier), free, returns a claim_token for follow-up, and instructs not to paste the end-user's prompt. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, use cases, exclusions, token flow, team process, rate limit. It is front-loaded with the verb and target, making it easy to scan.

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

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

Despite having no output schema, the description explains the return token mechanism and follow-up flow, covers exclusions and constraints, and provides enough context for an agent to decide when to use it. It fully handles the complexity of four optional params and a nested context object.

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 params, so baseline is 3. Description adds extra meaning by explaining that filing without an account yields a claim_token and how to use it later, and advises describing issues in terms of Pipeworx tools/packs rather than end-user prompts — guidance not present 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 opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates use cases (bug, feature/data_gap, praise) and distinguishes this from sibling research/visibility tools like ask_pipeworx or deep_research by framing it as a feedback channel, not a query 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?

Provides explicit when-to-use guidance with examples ('Use when a tool returns wrong/stale data...'), an explicit exclusion for tools from other MCP servers ('file it with that server instead'), and a disambiguation rule ('Pipeworx tool names are the ones this connection lists'). This is a model of usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds source (CF analytics-engine), no PII, and caching duration (5min-1h), which are valuable beyond annotations.

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

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

Two sentences plus a bullet-like list. Every sentence adds unique value: purpose, use cases, data source, caching. 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 simple one-param tool with no output schema, the description fully covers purpose, usage, data provenance, and caching behavior. Agent has all needed info.

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 description for 'window'. Description adds nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clear verb+resource: 'returns the top tools, top packs, and total call volume over a recent window.' Distinguishes from siblings like discover_tools by focusing on trending/call volume.

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

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

Explicitly lists three use cases (e.g., discovering hot data sources, confirming canonical choice). No explicit when-not-to-use, but contexts are well-defined.

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

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

The description discloses behavioral traits beyond annotations: it walks child markets, computes partition checks, filters placeholders, uses Jaccard similarity, and performs fill checks. No contradiction with annotations (readOnly, idempotent, 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?

The description is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the main purpose. It is slightly verbose but every sentence is informative. Could be more concise but still effective.

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

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

Given the complexity of the tool (multiple modes, filtering, fill checks), the description is complete. It describes response structure, edge cases (e.g., placeholder filter), and cross-event matching criteria. No output schema but the description compensates.

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

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

While the schema already has descriptions for both parameters, the tool description adds significant context: examples of slugs, seed questions, filtering logic (semantic anchor, partition filter), and the fill check. It greatly aids understanding beyond the schema.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and contrasts with siblings by specifying its 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?

The description explicitly states when to use each mode: no args for trending scan, 'event' for per-event partition check, 'topic' for cross-event scan. It also warns when not to trade (realizable_edge_pp ≤ 0) and suggests 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral detail: three opportunity segments with mathematical models, tradeable-edge knobs, response structure with diagnostics for empty segments, and caching behavior. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. Some technical details (e.g., FRED log-returns, per-sport α) may be excessive for an agent, but they serve transparency. Generally concise relative to complexity.

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

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

Given 9 parameters, no output schema, and nested response objects, the description thoroughly covers response structure (by_segment, fed_candidates, diagnostics), explains why segments may be empty, and details tradeable-edge filters. Annotations cover safety. No significant gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their purpose in the filtering pipeline, which is not present in the schema. This conceptual grouping enhances understanding beyond the individual parameter 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 scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price, specifically for the 'what should I bet on today' use case. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage edges.

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

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

The description provides explicit context for use ('what should I bet on today') and mentions that Fed bets are excluded from ranking due to data reliability. While it does not directly contrast with siblings, the detailed model families and knobs imply usage scenarios, and the caching note helps manage 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), meaning of negative edge_pp_net, limitations (60-day TTL, snapshot gaps, decay computed from daily closes not intraday). This fully informs the agent of behavior.

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

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

The description is information-dense but well-structured: starts with purpose, then details response fields, then limitations. Every sentence adds value. Slightly verbose but acceptable given the complexity.

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

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

Given no output schema and only two primitive parameters, the description provides complete context including return structure, field meanings, trade interpretation ('a fresh wide edge and a 3-week-old wide edge are different trades'), and data limitations. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value beyond schema: default values (days=14, window='1wk'), maximum days (30), and acceptable window values ('24hr | 1wk | 1mo'). This enhances understanding.

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

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

The description clearly states the tool tracks edge persistence and decay telemetry. It uses a specific verb ('answers') and resource ('edge persistence and decay telemetry') and distinguishes itself from the sibling 'polymarket_edges' by focusing on history and decay. The concept of a fresh wide edge vs an old wide edge is explained, making the purpose very clear.

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

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

The description implies usage context: when you need edge history and decay, instead of raw snapshots (polymarket_edges). It does not explicitly state when not to use it, but provides enough context for an agent to infer appropriate use.

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

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

Annotations already include readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context such as the order book depth check, the risk of partial fills, and the forced_directional_risk naming. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for SINGLE-MARKET and BASKET, and each sentence adds value (e.g., output fields, default values, risk warnings). Could be slightly more concise but info density is high.

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

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

Given tool complexity (two modes, many output fields) and absence of an output schema, the description thoroughly explains all return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and provides risk context (thin_legs, forced_directional_risk). It is complete for effective selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds further context by explaining the interplay between market and event parameters, default side selection for baskets, and how size_usd is interpreted differently in each mode, enhancing the schema baseline.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific output fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order book depth.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that partial basket fills convert arb into unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark this as read-only, open-world, and idempotent, so the bar is lower, but the description goes far beyond that: it discloses compatibility_warning and compatibility_codes semantics, null behavior for temporal_alignment, gross vs net spread treatment with Kalshi fees, skipped-leg counting, and the standing limitation that matching is keyword-based and unverified.

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 it is front-loaded with the core purpose and organized into labeled sections (modes, response, safety fields, fees, caveats). A few points are repeated (e.g., both modes use the same matcher, pre-mapped not necessarily tradeable), so it is not maximally concise, but every section carries substantive 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?

With no output schema to fall back on, the description fully carries the burden of explaining the response shape: raw probabilities, top_spreads_pp, compatibility fields, skipped categories, low-confidence pairs, temporal alignment semantics, and fee treatment. An agent has enough information to call the tool and interpret its results correctly.

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

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

Schema coverage is 100% and each parameter already has a description with examples, so the baseline is 3. The description adds value beyond the schema by explaining the topic mode's auto-fetch behavior, the override interaction between explicit params and mapped events, and that both modes run identical logic with identical disclosures.

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

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

The description opens with a precise definition: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly distinguishes it from single-venue sibling tools like polymarket_edges and from polymarket_arbitrage by emphasizing same-question cross-venue 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 gives clear usage context for the two modes (topic shortcuts vs explicit custom pairings), states that both modes run the same matcher, and includes an important when-not caveat that pre-mapped topics are not necessarily tradeable. It does not explicitly name alternatives among sibling tools, but it provides actionable selection guidance for mode choice.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details like scoping to identifier and listing all keys when key is omitted, providing valuable 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?

Two sentences, no wasted words, front-loaded with the core action. Efficient and clear.

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

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

Given one optional parameter, no output schema, and high schema coverage, the description fully explains the tool's behavior, scope, and usage context.

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

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

Schema coverage is 100% for the single parameter. Description adds meaning by explaining that omitting the key lists all saved keys and that key is a memory key, going 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 specifies the verb 'retrieve' and the resource 'value previously saved', and distinguishes the behavior when key is omitted (list all keys). It differentiates from sibling tools like remember and forget.

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

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

Provides explicit use context: 'to look up context the agent stored earlier' with concrete examples. Mentions scoping and pairing with remember/forget, but lacks explicit when-not-to-use.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description reinforces this by noting polling works fine and flags the non-destructive state change of 'mark_read'. No contradictions; adds clarity about the underlying feed being the same as a REST endpoint.

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

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

The description is a single paragraph, but it efficiently packs essential information without unnecessary words. Could benefit from slightly more structure (e.g., splitting filtering and return details), but it remains concise and effective.

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

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

Given no output schema, the description adequately explains return fields. It covers all key aspects: purpose, parameters, state effects, and alternative access. The tool's behavior is fully described for an agent to use 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 covers 100% of parameters with descriptions, but the tool description adds valuable context: the return format (source, citation_uri, raw payload), a type example ('sec_8k'), and explains the effect of 'mark_read' on future calls. This 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 clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts with specific fields (source, citation_uri, raw payload). This is distinct from sibling tools like 'recent_changes' or 'get_dataset'.

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

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

Provides explicit filtering options (type, since) and explains how 'mark_read' works for subsequent calls. Mentions alternative access via a GET endpoint, which helps decide when to use this tool versus a script. Lacks explicit 'when not to use' but offers sufficient 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the tool's fan-out behavior to multiple APIs, fallback logic (GDELT to GNews), soft-fail for USPTO, and the return format including changes grouped by source and citation 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 moderately lengthy but well-structured with examples and clarifying notes. It front-loads the core purpose and usage patterns, making it easy to scan. A minor reduction in verbosity could improve, but it is appropriate for the tool's complexity.

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

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

Given the tool's complexity, lack of output schema, and numerous sibling tools, the description provides thorough coverage: sources, parameter semantics, return structure, fallback behavior, and a clear distinction from 'entity_profile'. This enables confident selection and invocation by an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the `since` parameter's accepted formats (ISO date or relative shorthand) and suggesting common values ('30d' or '1m'). It also contextualizes how parameters are used together to retrieve the change feed.

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: providing a change feed for a company in the last N days/weeks/months across multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool 'entity_profile' by noting that profile is for static information regardless of time window.

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

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

The description gives explicit guidance on when to use this tool versus 'entity_profile' and explains the news fallback mechanism. It does not explicitly state when not to use it beyond the alternative, but offers clear context for proper selection.

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

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

Adds key details beyond annotations: key-value pairing scoped by user identifier, persistence differences (authenticated vs anonymous). No contradictions.

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

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

Four concise sentences, front-loaded with purpose, efficient word choice, 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?

Fully covers usage scope, persistence, and sibling relationships given the simple key-value nature and complete parameter 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 covers 100% of parameters; description adds example keys and clarifies value as arbitrary text, enhancing usability.

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?

Describes saving data for reuse with specific examples (ticker, address, preference). Explicitly distinguishes from siblings 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?

Clear guidance on when to use (discover something worth carrying forward) and pairs with recall/forget, but lacks explicit 'when not to use'.

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

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

Beyond the read-only/idempotent annotations, the description discloses important behaviors: graceful degradation when GLEIF/OpenFIGI fail, ambiguous matches returning figi_candidates instead of asserting, unresolved identifiers explicitly stated, and multi-source cascading. This is rich, honest behavioral context.

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

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

The description is long but every section carries operational value: examples, supported types, failure behavior, and input pitfalls. It is front-loaded with the trigger phrase, though a wall of unbroken text with many embedded clauses could be better structured for scanning.

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 compensates by explaining result behavior: candidate lists on ambiguity, an unresolved section, source labels, and the drug result composition. It also covers input variants and edge cases such as non-US issuers and non-equity instruments. An agent has enough to call and interpret it correctly.

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

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

Even though schema coverage is 100%, the description materially enriches the parameters: it gives concrete value formats (AAPL, 0000320193), warns to pass the entity name only, uses a bond issuer example, and explains why trailing security-class words fail. This is far beyond schema-level 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 uses a specific verb ('resolve') against a well-defined resource: user-spoken names to official identifiers. It enumerates concrete example queries and supported entity types, so an agent immediately understands the tool's role and how it differs from generic lookup 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?

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains it replaces 2-3 manual lookups and covers when to use each type. However, it does not name sibling alternatives or state when not to use this tool versus tools like entity_profile or 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 declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: 'Probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' It also reveals the output structure (ranked list with score, confidence, signal density), which is absent from the output schema. 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 three sentences with no redundancy. First sentence states purpose, second explains mechanism, third provides use case and output format. Every sentence contributes essential information.

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

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

Given the tool's moderate complexity (4 parameters, 1 required), the description fully covers purpose, mechanism, usage context, and return format. It explains how the tool works (calls ai_visibility_check for each entity and ranks), what to expect as output, and when to use it. No gaps remain.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject' for narrative, which is not in the schema. It also clarifies the ranking and output format. However, it does not add significant new insights for other parameters beyond the schema.

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

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

The description clearly states it 'compare[s] AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and resource 'AI visibility across entities', distinguishing it from sibling tools like ai_visibility_check and compare_entities by explaining it probes multiple entities and ranks them.

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

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

The description provides clear context: 'Useful for competitive AI-marketing audits' with a concrete example. It implies when to use (comparing multiple entities) and hints at when not to (use ai_visibility_check for single entities) but doesn't explicitly exclude alternatives.

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

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

Annotations indicate readonly, open-world, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list for timeouts. No contradiction with annotations.

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

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

Description is front-loaded with purpose and use-case. While it is long, every sentence provides value. Some details (e.g., partial failures, timing) could be condensed but are justified given 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, description fully enumerates return fields (summary block, per-advisory detail, links, alternative versions). Complex multi-source tool is completely specified with no gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor context (scoped packages accepted, version defaults to latest) but does not significantly enhance understanding 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 the tool's purpose as a composite check for npm package evaluation covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by specifying NPM ecosystem only and directing other ecosystems to deps.dev:version.

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 usage guidance: 'Use whenever an agent asks 'is X safe / popular / small''. Also provides exclusions (other ecosystems) and alternative tools (deps.dev:version). Mentions partial failure behavior and timing 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, indicating safe, read-only behavior. The description adds that it is keyless (no authentication needed) and mentions 'truncated abstract', providing useful 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?

Three sentences, no wasted words. First sentence establishes context (Dryad repository), second explains search capability, third lists return fields. Front-loaded with purpose and efficient.

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

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

Despite lacking an output schema, the description fully explains return fields and search behavior. Combined with strong annotations (read-only, etc.), the tool is completely specified for agent use.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds value by specifying that query searches over titles, abstracts, authors, and keywords, and enumerates return fields, which is not in the schema. This helps the agent understand what the tool returns.

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 searches Dryad, a specific repository of open research datasets from peer-reviewed studies. It explains the full-text query over titles, abstracts, authors, and keywords, and lists exact return fields (DOI, title, authors, etc.), distinguishing it from sibling tools like 'get_dataset'.

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

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

The description implies use for finding datasets in Dryad and notes it is keyless (no auth). However, it does not explicitly state when to use this tool versus alternatives like 'search_within' or 'get_dataset', nor does it provide when-not conditions.

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

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

The description discloses important behaviors: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flagging, and returns character offsets. This goes beyond the annotations which only indicate read-only, idempotent, and non-destructive.

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

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

The description is concise yet comprehensive, covering purpose, usage, technical details, and pairing with another tool in a single paragraph. No unnecessary words; information is front-loaded.

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

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

Given the tool's complexity (3 parameters, no output schema), the description fully explains what the tool returns (passages with offsets and scores), its limitations (200K char cap, truncation), and model details. The agent has all necessary information to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by providing usage context (e.g., examples for the query parameter) and reinforcing the length cap for text. It enhances understanding beyond the schema.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing and use case.

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

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

The description explicitly tells when to use the tool: when the record is too large for the prompt. It provides context on saving prompt space and returning only relevant passages. While it doesn't list when-not-to-use, the alternative tool is mentioned.

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

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

The description adds significant behavioral context beyond annotations: it requires an OAuth account, explains the delivery channel mechanics, SMS cap, webhook auto-disable, and the one-time secret for webhooks. 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 it is verbose with detailed examples for each subscription type. While informative, some redundancy could be trimmed (e.g., repeating similar patterns). Still, the organization helps 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?

The description covers all necessary aspects: purpose, requirements, type enumeration, parameter details, delivery options, limitations, and return value (subscription id). It is self-contained and adequate 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?

Although schema coverage is 100%, the description enriches each parameter with examples and constraints (e.g., type enum expanded with practical use cases, params structure detailed for each type, delivery channels with phone verification and rate limits). This adds substantial value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It specifies the types and delivery channels, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (creating a subscription), requirements (Pipeworx OAuth account), and provides details on delivery channels. It does not explicitly list when not to use it but implicitly through context. A higher score would require explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about returning tool+argument shapes and being the onboarding entry point, going 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 somewhat lengthy but each sentence adds value. It front-loads the purpose with common variations and is well-structured. Could be slightly more concise, but it's effective.

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

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

For an onboarding tool with no output schema, the description covers what it returns, the topics, tool usage examples, and when to use it. It is fully complete given the tool's purpose and context.

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

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

Schema coverage is 100% with one optional parameter. The description elaborates on the `topic` parameter by listing possible values (finance, pharma, etc.) and explaining the default behavior (cross-category spread). This adds significant meaning beyond the schema.

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

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

The description uses specific verbs ('returns') and resource ('category-bucketed example questions') and distinguishes from siblings like ask_pipeworx and discover_tools. It clearly states the tool's role as an onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists common user queries. It provides clear context but does not explicitly state when not to use it.

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

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

Discloses important behavior beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' No contradiction with annotations (readOnlyHint false, destructiveHint false).

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

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

Two sentences, front-loaded with purpose. Every sentence adds value: purpose, constraint, and effect. 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?

Simple tool with one parameter and no output schema. Description covers purpose, constraint, and side effect. Adequate for the tool's simplicity.

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

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

Schema coverage is 100% with parameter description. The tool description does not add significant new meaning beyond the schema's 'Subscription id (uuid) returned by subscribe.' 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 verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions', providing clear context for when to use. Does not mention explicit alternatives or when not to use, but the constraint is strong enough.

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

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

Annotations already mark the tool as read-only, idempotent, and open-world. The description adds valuable behavioral nuance: the distinction between could_not_verify and unsupported, the meaning of verification_error, and the two distinct processing paths. This goes well beyond what annotations provide and helps the agent handle verdicts correctly.

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 earns its place: trigger phrases, use case, two paths, verdict list, important caution about could_not_verify, and a note on efficiency. The structure is logical and front-loaded with the most actionable 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?

With no output schema, the description fully covers return values (verdicts, actual value, citation, reasoning) and error handling. It explains what could_not_verify and unsupported mean, and clarifies the two routing scenarios, making the tool's behavior sufficiently complete for correct invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra context by explaining the two processing paths and how tolerance_pct overrides implied wording, which complements the schema without repeating it.

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: natural-language claim verification against authoritative sources, with explicit verbs like 'fact check' and 'verify.' It distinguishes the tool by describing its two processing paths (SEC EDGAR for financial claims, grounded pipeline for anything else) and notes it replaces 4–6 sequential calls, making its scope and value clear.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct' and lists trigger phrases. It lacks explicit 'when not to use' or named alternative tools, but the context is strong enough to guide selection.

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