Sefaria

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it probes LLMs, returns per-model data with raw responses, and notes the cost implications of the Anthropic key 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 concise with three sentences, front-loaded with purpose, and avoids unnecessary detail. Every sentence adds value.

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

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

Despite no output schema, the description fully explains the return structure (per-model and combined view). All parameters are covered, and the tool's behavior is adequately described for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and the description enhances understanding by clarifying the default model, the passthrough nature of _apiKey, and the disambiguation role of context. It adds value beyond the schema without being redundant.

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 probes LLMs for visibility of a business or topic, scores it 0-100, and identifies the default model. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on a single entity and providing per-model scores.

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 outlines concrete use cases like AI-marketing audits and pre-launch checks, and explains when to provide an Anthropic API key. However, it does not explicitly state when not to use this tool or mention direct alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds context about internal routing across 5,344 tools and 1,393 sources, auto-filling of arguments, stable citation URIs, and 'one fast call' performance, which goes beyond the annotations without contradicting them.

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

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

The description is thorough and front-loaded, but it is somewhat verbose and contains redundancy (e.g., 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it'). While each sentence adds some value, the overall length and repetition detract from conciseness.

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 a simple one-parameter schema and no output schema, the description is remarkably complete. It explains the tool's internal mechanics, return format (citations), performance, and relationships to sibling tools. It could mention edge cases or limitations, but for selection and invocation purposes it is sufficient.

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

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

The input schema has 100% coverage, with all parameters being aliases of 'question' and a clear description. The tool description adds value by providing examples of appropriate question types and the kinds of topics covered, effectively guiding parameter usage beyond the schema's terse 'Alias for question'.

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: it routes factual questions to a large set of verified sources, fills arguments, and returns structured answers with citation URIs. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, making the purpose unmistakable.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists specific triggers (e.g., 'what is', 'look up', 'find') and examples. It also states when to step up to more specialized tools, covering both when-to-use and 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 declare readOnly, idempotent, openWorld, and non-destructive. The description goes beyond by explaining that no candidate is currently active, that it currently matches ask_pipeworx, and that it is a full working router with no fallback. It clearly discloses the experimental edge (candidate routing under test) and the comparison mechanism, giving rich behavioral context 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, front-loaded paragraph of four sentences. Each sentence earns its place: purpose, current status, usage, and clarification that it's fully functional. There's slight redundancy ('identical' and 'same' used repeatedly), but overall it's tight and well-structured.

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

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

Given the tool's complexity (universal router over 5,344 tools) and lack of output schema, the description is sufficient. It explains the response shape ('same response shape'), the scale, the experimental nature, and the current equivalence to ask_pipeworx. An agent has everything needed to select and invoke the tool appropriately.

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

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

Schema coverage is 100%, and every parameter is an alias for 'question' with a description. The description doesn't add parameter-level detail (it only says 'same arguments'), but the schema already fully specifies semantics. Baseline 3 applies because the schema does the heavy lifting and the description doesn't add meaning beyond that.

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+resource: 'identical universal router' that answers questions by routing to one of 5,344 tools. It clearly distinguishes itself from ask_pipeworx as the beta version with candidate routing improvements, and references ask_pipeworx_grounded implicitly. The scope and experimental nature are explicit.

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

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

The description gives an explicit when-to-use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, implying it's for testing or experimental use. However, it doesn't explicitly state when NOT to use it (e.g., for production workloads), so it's not a full 5.

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

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

Discloses that the tool extracts answers only from tool results, can return explicit refusals with detailed reasons (not_in_source, no_tool_match, etc.), and incurs an extra LLM call compared to ask_pipeworx. This contextualizes behavior well beyond the readOnly/idempotent annotations, without contradicting them.

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

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

The description is dense but efficiently structured: it states what the tool does, how it differs from ask_pipeworx, the exact response format, refusal reasons, when to use, and cost trade-off. Every sentence adds value, and the layout front-loads the core distinguishing trait (grounded extraction).

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 fully compensates by detailing success and refusal response structures, enumerating refusal reasons, and covering use cases and cost. It is complete enough for an agent to understand behavior, return values, and trade-offs without needing additional documentation.

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

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

The schema already describes the question parameter and all aliases with 100% coverage, so the description adds no additional parameter-level meaning. The baseline of 3 applies because the schema does the heavy lifting, and the description only references the question indirectly ('fills arguments').

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 routes like ask_pipeworx but grounds answers solely in tool results, with explicit refusal semantics. It distinguishes from siblings by emphasizing evidence-based extraction and refusal behavior, making the tool's purpose unmistakable.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), and even names the alternative. This provides clear, actionable guidance for tool selection.

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

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

Annotations already indicate readOnly, idempotent, openWorld, non-destructive. The description adds extensive behavioral context: blocking paths (low_confidence_match, market_closed_or_inactive), safety short-circuits, spread detection, resolution rule risk, and cancellation rule parsing. This far exceeds what annotations provide, and there is no contradiction.

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

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

The description is long but well-structured with sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY) and front-loaded with the core purpose. Every sentence provides necessary detail for a complex tool, though some could be condensing without losing critical information.

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

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

Given the tool's complexity (multiple classifiers, fan-out, edge cases, response shapes, resolution rules), the description is remarkably complete. It covers inputs, outputs, error states, safety, and even resolution rule risk. With no output schema, the explanation of response shapes is essential and well provided.

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

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

Schema covers 100% of parameters with descriptions. The description adds context about the market parameter formats and includes examples, but does not significantly enhance parameter semantics beyond the schema. 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 starts with a clear verb and resource ('Research a Polymarket bet by pulling the relevant Pipeworx data'), and explains the overall task. It is specific but does not explicitly distinguish from sibling tools like polymarket_edges or polymarket_arbitrage, though its unique focus on a single bet is implied.

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 includes explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains behavior for different bet types (e.g., BTC, Fed, sports) and includes blocking conditions, but does not mention when NOT to use it or suggest alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral details: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorted results, and citation URIs.

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

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

The description is somewhat long but well-structured with trigger phrases at the beginning, and every sentence contributes valuable information. No wasted words.

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

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

Given no output schema, the description explains returned data per type (e.g., revenue, net income for companies; FAERS counts for drugs) and the presence of citation URIs. Covers essential aspects 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 coverage is 100%, but the description adds context: max/min constraints, examples, and explain that value format differs by type (tickers vs drug names). Also mentions fiscal year handling for company type.

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

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

The description uses specific verbs ('compare') and resources ('entities'), and distinguishes from sibling tools like entity_profile by emphasizing side-by-side comparison of multiple entities in one call.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides trigger phrases ('which is bigger', 'rank these companies'), with clear differentiation between company and drug use cases.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral detail: it returns a findings packet with citations, gaps[], contradictions[], performs semantic excerpting, never invents answers, and provides timing expectations. This goes far beyond the annotations and fully discloses the tool's behavior.

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

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

The description is dense and front-loaded with account requirements and key differentiators. It is longer than ideal, with minor redundancy (citations and contradictions are each mentioned twice), but every sentence carries substantive information. Overall, it is well-structured and earns its length.

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

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

With no output schema, the description fully explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, gaps[], and contradictions[] for certain depths. It also covers account tiers, response times, and error behavior. This is exceptionally complete for a tool with two parameters.

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

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

Schema coverage is 100% for both parameters. The description adds valuable semantics for the 'depth' parameter (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop, paid), and clarifies that 'question' can be broad/multi-part. This is valuable extra context beyond the schema.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call'. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making the tool's unique purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names an alternative tool and explains account prerequisites.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond these: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This discloses output format and reusability, which is valuable for an agent. No contradiction with annotations.

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

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

The description is well-structured: first sentence captures purpose, then lists domains, then describes output, then gives usage guidance. It is moderately concise but front-loaded with key information. Could be slightly trimmed, but every sentence earns its place.

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

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

Given the tool's complexity (discovery of many domains) and lack of output schema, the description provides sufficient completeness: it explains the return format (names, descriptions, schemas) and that results are callable directly. It does not detail exact output structure but is adequate for an agent to understand the tool's value.

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

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

Schema coverage is 100%, so baseline 3. The description mentions example queries like 'analyze housing market trends' but does not add deeper meaning beyond what the schema already provides for parameters. The schema lists 'query' and aliases with descriptions; the description merely reinforces these.

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: 'Find tools by describing the data or task.' It specifies the verb ('find') and resource ('tools'), and distinguishes itself from siblings by listing domains it covers and emphasizing it is for browsing/discovery, not for querying specific data.

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

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

Explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It tells when to use (instead of guessing or picking randomly) and what it returns (top-N relevant tools). This clearly differentiates from sibling tools that are more specific.

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 and idempotentHint. Description adds valuable details: returns specific fields like recent_filings with URIs, fundamentals sorted by period_end, and notes that patent data soft-fails after May 2025. This goes beyond annotations.

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

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

Description is front-loaded with example queries and a strong usage directive. While slightly verbose, each sentence adds value (e.g., explaining patent sunset, fallback mechanisms). Could be trimmed slightly but overall efficient.

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

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

No output schema exists, so description carries full burden of explaining return values. It comprehensively lists cik, company_name, recent_filings (5 max with URIs), fundamentals, patents (with caveat), news via GDELT→GNews, and LEI. Edge cases like name-only queries are addressed.

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

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

Schema covers 100% of parameters with descriptions. The description adds context: explains that value accepts ticker or zero-padded CIK, and that names are not supported. Also clarifies that type is currently limited to 'company'.

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

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

Description clearly states the tool returns a full cross-source profile of a US public company, with specific examples like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from sibling tools like resolve_entity by noting that names are not supported.

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

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

Explicitly advises to prefer this tool over chaining single-source lookups when a holistic view is needed. Also provides a clear alternative: use resolve_entity first if only a name is available.

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. Description aligns with this and adds context about clearing stale or sensitive data, which enhances transparency 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?

Two sentences, no wasted words. Purpose is front-loaded. Every sentence is informative and earns its place.

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

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

Given the tool's simplicity (one param, no output schema, annotations present), the description covers key usage and purpose. Slight gap: no mention of return value or error behavior, but acceptable for a low-complexity tool.

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

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

Schema description coverage is 100% for the single parameter 'key'. The description only says 'by key', adding no new semantics beyond the schema. Baseline 3 per guidelines.

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', identifying the action (delete) and the resource (memory by key). It distinguishes from siblings like 'remember' and 'recall' by mentioning 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?

Explicit when-to-use guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and it suggests pairing with related tools '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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is a 'single text blob ready to drop at site-root/llms.txt,' which helps the agent understand the result. It does not contradict annotations.

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

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

The description is three sentences long, each adding value: main purpose, process, and use cases. It is front-loaded, efficient, and contains no redundant information.

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

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

Despite lacking an output schema, the description explains the output format ('standard llms.txt markdown format' and 'single text blob'). It covers the tool's inputs, process, and output adequately. For a simple generation tool with two parameters and clear behavior, this is complete.

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

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

Schema description coverage is 100% (both parameters are described in the schema). The description does not add new semantic details beyond what the schema provides (e.g., format constraints on the URL or link count limits). Baseline score of 3 is appropriate.

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

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

The tool name and title clearly indicate generating an llms.txt file. The description specifies the verb 'Generate' and the resource 'llms.txt file', and explains the process: fetches page, extracts title/description/key links, emits standard markdown. It is specific and distinct from sibling tools, which are unrelated.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing), giving clear when-to-use guidance. It lacks explicit when-not or alternative tools, but the uniqueness of the tool makes this less critical.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds the keyless (no authentication needed) aspect, which is meaningful beyond annotations. No contradictions.

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

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

The description is a single, clear sentence with no wasted words. It is front-loaded with the core action and resource.

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 (3 params, no output schema, rich annotations), the description provides enough context to understand usage. It could mention default values or return format, but schema covers defaults. Overall, sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal new meaning (e.g., 'quoting commentaries' and example values), but does not significantly extend 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 lists commentaries and cross-references on a passage, with specific examples (Rashi, Targum) and a source (Sefaria's link graph). This distinguishes it from sibling tools like get_text or lookup_ref.

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 examples but does not explicitly state when to use this tool versus alternatives (e.g., get_text for the text itself). Usage is implied through the purpose, but no when-not or alternative guidance is given.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds useful context: 'Keyless' (no auth required) and the scope of supported texts, which goes beyond annotations.

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

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

Two sentences that are dense with information: specifies action, resource, scope, and keyless access. No unnecessary words.

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

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

The tool is simple (2 params, no output schema). The description adequately covers purpose, supported text types, and language options. It doesn't detail return format, but it's acceptable for a straightforward fetch 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 examples and descriptions for both 'ref' and 'language'. The description mentions 'in Hebrew and/or English' which aligns with the language parameter, but does not add significant new meaning beyond the schema.

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

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

The description uses a specific verb ('Fetch') and resource ('passage of Jewish text from Sefaria by reference'), lists supported text types ('Torah/Tanakh, Talmud...'), and clearly distinguishes from siblings like 'get_commentaries' which has a different purpose.

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

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

The description states it works for a wide range of Jewish texts and mentions 'Keyless', implying no authentication needed. However, it does not explicitly exclude cases or name alternatives, but the context is clear for typical use.

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

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

Annotations already declare readOnlyHint: true, idempotentHint: true, destructiveHint: false. Description adds value by specifying default behavior (active only), ability to include inactive via parameter, and exact return fields. 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 clear sentences, no filler, front-loaded with purpose and return fields.

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

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

For a simple read-only list tool with one optional param and no output schema, the description covers purpose, return format, usage guidance, and parameter effect completely.

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

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

Schema coverage is 100% (1 parameter fully described). Description does not add extra meaning beyond the schema, baseline 3 applies.

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

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

Description explicitly states 'List the caller's active subscriptions' and enumerates return fields (id, type, etc.), clearly distinguishing it from sibling tools like subscribe (creation) and unsubscribe (cancellation).

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel', telling when and why to use the tool.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds that it returns validity and completions, and notes 'Keyless', but does not elaborate further. Overall, annotations carry most of the burden here.

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 filler, front-loaded with the action and outcome. Every word earns its place.

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

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

For a simple validation tool with one parameter and no output schema, the description adequately explains input and output. It could hint at case sensitivity or language support, but this is minor.

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 'name' parameter. The description does not add significant additional meaning beyond 'keyless', which is not directly related to the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool validates or autocompletes a Sefaria reference/title, with examples. It distinguishes from sibling tools like get_text or search_within that operate on valid references.

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 validate/autocomplete references, which guides when to use. However, it does not mention when not to use or provide alternatives among siblings, though the context implies its role for validation before other operations.

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 rate limit (5 per day), free usage, and how feedback is used (affects roadmap). Add beyond annotations which only deny read-only and destructive hints.

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

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

Concise 4-sentence description with front-loaded purpose, then guidelines, then constraints. No unnecessary words.

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

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

Covers all aspects: what, when, how, constraints, and impact. No output schema needed, and the simple tool is fully described.

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

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

Schema coverage is 100%, but description adds context for enum values and clarifies message format (specific, 1-2 sentences, no prompt pasting).

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

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

Clearly states the tool sends feedback to Pipeworx about bugs, missing features, or praise. Distinct from siblings which are query/research tools.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and what not to do (paste end-user prompt). Also explains rate limits and daily digests.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing behavioral traits: self-aggregating signal, derived from CF analytics-engine, no PII, only (pack, tool, count) data, and caching from 5min to 1h. This goes beyond what annotations cover. 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 paragraphs: first states purpose and parameters, second lists use cases. Every sentence adds value. No wasted words. Well-structured and front-loaded.

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

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

For a simple tool with 1 parameter, no required params, full schema coverage, and rich annotations, the description is complete. It explains what is returned, data derivation, privacy, caching, and use cases. No output schema is needed as return is conceptually described.

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?

Only one parameter (window) with full schema coverage and enum descriptions. The description repeats the windows but does not add significant meaning beyond the schema. Baseline 3 is appropriate as schema already does the heavy lifting.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses specific verbs like 'Returns' and specifies the resource. It distinguishes itself from siblings by noting it shows what other AI agents are calling on Pipeworx, which is unique among the listed sibling tools.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming popular tools, and aligning use case with agent needs. It implicitly guides when to use it (e.g., for current events) but does not explicitly mention when not to use or compare with sibling tools like 'discover_tools', so there is room for improvement.

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, openWorldHint), the description details behavioral traits such as monotonicity violation checks, partition-sum logic, fill check against live CLOB depth, and semantic anchor similarity. It also explains response structure and when not to trade, adding significant value beyond annotations.

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

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

The description is well-structured with sections for each mode and additional details on semantic anchor, partition filter, response, and fill check. Every sentence adds value, and the information is front-loaded with the core purpose. Despite length, it remains concise and relevant.

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

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

Given no output schema, the description thoroughly explains the response fields (opportunities[], partition_check, fill_check) and provides cross-reference to polymarket_fill_risk for custom sizing. Annotations cover safety. All necessary context for an AI agent to use the tool correctly is present.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description goes further by explaining the meaning of event slug vs. topic, providing examples, and detailing the behavioral difference between the two modes, thus adding substantial 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 function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage.

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 per mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event mode for specific markets and explains when to use cross-event mode. Includes semantic anchor and partition filter details for informed usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds extensive behavioral details: caching at 1h KV level keyed on all knobs, output structure with by_segment and diagnostics, explanation of model families and edge calculation, and tradeable-edge knobs. 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 long but every sentence adds value. It is front-loaded with the core purpose and segment overview, then details each model family, response structure, knobs, and diagnostics. No fluff; information is dense but well-organized.

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 (9 optional parameters, 100% schema coverage, no output schema), the description covers all essential aspects: purpose, model families, response structure with by_segment and diagnostics, tradeable-edge knobs, caching behavior, and even explains why Fed bets are excluded. Highly complete.

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

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

Schema coverage is 100% and the description adds significant meaning beyond parameter names and types. It explains the purpose of each knob (e.g., slippage_pp, min_liquidity, max_spread_pp), provides default values, and clarifies how parameters interact (e.g., min_partition_leg_kelly vs min_kelly).

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on market inefficiency detection based on Pipeworx's proprietary signals.

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

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

The description explicitly states the use case: 'what should I bet on today' and mentions that agents can discover opportunities without paging hundreds of markets. It provides guidance on tradeable-edge knobs and diagnostics, but does not explicitly mention when to use alternatives like polymarket_arbitrage.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds significant behavioral details: explains response structure (tracked, expired, snapshot_dates), limits (60-day TTL, data start), and that decay numbers are based on daily closes. 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 comprehensive and well-structured, front-loading the purpose and then explaining the response. While lengthy, every sentence provides valuable information. Minor redundancy in repeating defaults mentioned in schema.

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 edge tracking with time series and no output schema, the description thoroughly explains what the response contains (tracked, expired, snapshot_dates) and limitations (TTL, data start, intraday vs daily). Complete enough 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 coverage is 100% with good descriptions for both parameters. The description adds further context (defaults, max for days, clarification of window family) that 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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes from sibling tools like polymarket_edges (which likely provides current edges).

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

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

The description implies usage for historical edge analysis (answering 'how long has this edge existed and is it shrinking?') and mentions the alternative of a fresh edge versus an old one. While not explicit, it provides enough context to understand when to use this tool.

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

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

Discloses that it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and warns that partial basket fills convert an arb into an unhedged directional position. Annotations (readOnly, idempotent) are consistent and augmented by description details. No contradiction.

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

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

The description is thorough but slightly long; however, it is well-structured with clear mode sections and front-loaded purpose. Every sentence contributes useful information, though minor redundancy could be trimmed.

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 complexity (two modes, 4 parameters, no output schema), the description is complete: explains return fields, behavior, and risk implications. Covers all necessary context for correct usage.

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

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

Schema coverage is 100%, and description adds meaningful context: explains side defaults (buy_yes for single-market, auto for basket), size_usd interpretation (max spend vs target proceeds), and clarifies required parameter (one of market or event). Adds value beyond schema.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth', specifies two distinct modes (single-market and basket), and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround not capturable and partial fills create directional risk. Provides clear when-to-use and when-not-to-use context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant context beyond these: explains compatibility warnings (shape mismatches, semantic mismatches), temporal alignment, and skipped cross types. It does not contradict annotations.

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

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

The description is fairly long but well-structured: it starts with the core purpose, then details modes, response fields, and safety warnings. Almost every sentence adds value, though some duplication (e.g., compatibility warning explanation) could be tightened. It front-loads 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 complexity (three parameters, no output schema, no nested objects), the description is highly complete. It explains output structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and potential pitfalls. It compensates for the lack of output schema by describing key return fields.

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

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

Schema coverage is 100% (all three parameters described). The description adds context about the topic shortcuts listing and explains that explicit tickers override the topic side. However, the schema already describes the parameters similarly; the description does not add major new semantic meaning beyond usage context.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('Cross-venue spread') and resources ('Kalshi and Polymarket'), and distinguishes from sibling tools by its explicit focus on venue comparison rather than single-venue analysis.

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

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

The description specifies two modes (topic shortcuts and explicit tickers) and explains when each is appropriate. It warns that most pre-mapped topics may return compatibility warnings, indicating when not to rely on the result. However, it does not explicitly compare to sibling tools like polymarket_arbitrage, which could help an agent choose between them.

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

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

Annotations indicate read-only and idempotent. Description adds context about scoping to identifier and relationship to save/delete actions, which enhances transparency 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?

Three sentences, each with a clear role: action, use case, scoping/partnership. No redundant words.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers retrieval, listing, scoping, and relationships. 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% and already explains that omitting key lists all keys. Description adds examples but does not significantly extend beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves a saved value or lists all keys when the key is omitted. It uses specific verb-resource pairs and distinguishes from siblings 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 when-to-use guidance with examples (target ticker, address, notes). Mentions scoping and pairing with remember/forget. Does not explicitly exclude alternatives but is clear enough.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description aligns, explaining that it reads fired events and can optionally mark them as read. Adds context about return fields and polling behavior beyond annotations.

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

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

Description is a single paragraph of four sentences, front-loaded with the main purpose. It is efficient and includes necessary details 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?

The tool has no output schema, but the description compensates by listing key return fields. It also covers filtering, mark_read side effects, and provides an alternative endpoint, making it fully informative for an agent.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by clarifying usage of 'type' (with example 'sec_8k'), 'since' (ISO timestamp), and 'mark_read' (flags events read for next call).

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 a subscription feed, with details on return fields (source, citation_uri, payload). It distinguishes from siblings like 'list_subscriptions' by specifying the feed behavior and filtering options.

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

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

Provides guidance on filtering by type and since, and explains mark_read semantics for controlling read state. Mentions polling suitability and an alternative endpoint, but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context beyond annotations: it fans out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO), describes fallback logic, mentions soft-fail for patents, and details the return structure (grouped changes, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is concise (3 sentences) and well-structured: front-loaded with query examples, then explains data sources and fallback, then parameter notes. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats) and lack of output schema, the description is complete. It explains the return format (changes array, total_changes, citation URIs) and covers all necessary behavioral aspects.

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 providing concrete examples for 'since' (ISO date and relative like '7d', '30d'), explaining that 'value' can be a ticker or zero-padded CIK, and clarifying that 'type' only supports 'company'. This enriches 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 provides a change feed for a company (SEC filings, news, patents) within a time window, using specific verbs like 'change feed' and explicitly distinguishing from the sibling tool 'entity_profile' which returns static profile data.

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

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

The description gives explicit examples of when to use the tool (e.g., 'What's new with X', 'latest on Y') and explicitly states to use 'entity_profile' instead when a static profile is needed regardless of window. It also covers fallback behavior between GDELT and GNews for news sources.

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 idempotentHint=true and destructiveHint=false, which is consistent with 'save' operation. Description adds valuable behavioral details: key-value store, scoping by identifier, persistence differences for authenticated vs anonymous users (24-hour retention). No contradiction.

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

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

Description packs all essential information into a single, well-structured paragraph without redundancy or fluff. Front-loads purpose and usage, then adds behavioral details, 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?

For a simple 2-parameter tool with no output schema, the description provides complete guidance: purpose, usage scenario, persistence behavior, and sibling tools. Agent has all needed context to invoke correctly.

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

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

Schema coverage is 100% with descriptive parameter descriptions. Description adds user-meaningful context by providing example key patterns (e.g., 'subject_property') and value types ('findings, addresses, preferences, notes'), enhancing understanding beyond schema.

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

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

Description clearly states verb and resource ('Save data'), specifies reuse context across sessions, and lists concrete examples (ticker, address, preference). Distinguishes from siblings recall (retrieve) and forget (delete) implicitly by naming them as pairs.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and mentions alternative tools (recall, forget) with explicit pairing instructions. Also provides context for authentication and session duration.

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, and destructiveHint=false. The description adds valuable context about internal cascading lookups and efficiency (replaces 2-3 manual lookups), 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 well-structured, beginning with examples, then stating the purpose, followed by usage guidance and details on supported types. Every sentence serves a clear purpose without redundancy, and the length is appropriate for the complexity.

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

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

For a tool with no output schema and two entity types, the description thoroughly covers what the tool returns for each type, including specific fields and citation URIs. It also mentions internal cascading behavior. No gaps remain given the absence of 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%, but description adds significant meaning beyond the schema: it explains each parameter's usage with examples (ticker, CIK, name for company; brand/generic for drug), mentions auto-disambiguation for company names, and details the output contents (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug).

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

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

Description starts with concrete user queries and explicitly states the tool resolves names to official identifiers. It distinguishes from sibling tools by directing to use this tool 'FIRST' when a name-to-ID conversion is needed. The verb 'resolve' and resource 'entity' are specific and 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 advises 'Use FIRST whenever you have a name but need an ID,' providing clear context. It lists supported types (company, drug) and hints that it replaces multiple manual lookups, but does not explicitly state when not to use it or compare to alternative tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it probes each entity, ranks results, and returns score, confidence, signal density. No contradiction. It doesn't cover rate limits or auth details beyond the schema, but it aligns with and enriches the annotations.

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

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

Two sentences with no wasted words. Front-loaded with the main action. Could be slightly more structured but is effective 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?

Given no output schema, the description explains the return format (ranked list with score, confidence, signal density per entity). All four parameters are described in the schema and reinforced in the description. Sufficient for an agent to understand inputs and outputs.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: first entity is 'subject' for narrative, context disambiguates, models includes free vs paid. It doesn't add deep syntax or format details 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check and compare_entities.

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

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

The description provides a clear use case: competitive AI-marketing audits, with an example query. It implies when to use (compare brands) but does not explicitly state when not to use or name alternatives, though the purpose is distinct.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds significant behavioral context: composite nature, partial failure modes, bundlephobia first-measurement delay of 5-30s, sources_failed field. 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?

Description is information-dense but well-structured. First sentence states core purpose and services. Later sentences add usage guidance, ecosystem scope, and failure behavior. Slightly long but every sentence adds value; could be broken into clearer sections but is not overly verbose.

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

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

Despite no output schema, description lists return fields explicitly: summary block fields, per-advisory detail, links, recent versions. Also covers partial failure and list of failed sources. Missing exact structure of nested fields for advisories, but overall sufficient for an agent to understand what to expect.

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% (both parameters described). Description adds value by clarifying that scoped packages are accepted for 'package' and that version defaults to latest when omitted. These are useful nuances 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?

Clearly states it's a composite check for npm packages using deps.dev and bundlephobia. Distinguishes itself as a one-call solution for evaluating 'is X safe/popular/small' and specifies ecosystem limitation to npm in v1, with alternatives for other ecosystems.

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 when agent asks about safety/popularity/size or cost of adding a package. Mentions ecosystem boundary and alternatives for non-npm ecosystems. However, does not compare directly with sibling tools like 'validate_claim' or 'entity_profile', though the specific use case is distinct enough.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), and a 200K character cap with truncation flagging. This adds significant behavioral context not available from 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 four sentences, each serving a distinct purpose: stating the core function, explaining when to use, describing pairing with another tool, and providing technical details. No wasted words, and the most critical 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 (semantic search, embedding model, truncation, offset return) and the absence of an output schema, the description adequately explains the return format (top-N passages with offsets and scores). It also covers truncation behavior and tool pairing, providing a complete picture for the agent.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds minimal additional meaning beyond what the schema already provides (e.g., mentions max ~200K chars and default limit, but schema already has those). Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the action ('search INSIDE'), the resource ('a fetched record'), and how it differs from alternatives like ask_pipeworx_grounded. It explicitly mentions using it when records are too large for the prompt, distinguishing it from simply using raw text.

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

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

The description provides explicit guidance on when to use the tool ('when the record is too big to cram into the prompt') and suggests a complementary tool (ask_pipeworx_grounded) for grounding over retrieved passages. This clarifies both usage context and alternatives.

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

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

Annotations indicate idempotent=true, readOnly=false, destructive=false. The description adds substantial behavioral detail: subscription id returned, OAuth requirement, type-specific parameters, delivery constraints (phone verification, 10 SMS/day, webhook signing secret, auto-disable after 10 failures). No contradictions.

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

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

The description is front-loaded with purpose and return, then systematically covers requirements, types, and delivery. It is dense but not excessively verbose; every sentence adds value. Could be slightly more concise.

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

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

Given 3 parameters, no output schema, and tool complexity, the description covers essential aspects: required auth, type parameters, optional delivery with constraints. It does not mention idempotency explicitly or subscription limits, but openWorldHint allows for some omission. Overall thorough.

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 goes beyond schema by providing detailed examples for each type and delivery channel (e.g., phone verification, webhook signing). Minor issue: description lists only three types in the text while schema includes five, but schema covers all.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription ID. It distinguishes from siblings like list_subscriptions (view) and unsubscribe (remove).

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: it requires a Pipeworx OAuth account, explains supported types and delivery channels, and gives examples. However, it does not explicitly state when not to use this tool or contrast with alternatives like list_subscriptions.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context by explaining that the tool returns example questions with tool+argument shapes drawn from a live catalog, which is 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 core purpose and example queries. It is structured with bullet points for topic categories and usage guidance. Every sentence adds value, though slightly verbose.

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

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

Given the tool's simplicity (one optional parameter, no output schema, comprehensive annotations), the description provides sufficient context: what it returns, when to use it, and how to call it with or without arguments.

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

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

The input schema covers 100% of the single optional parameter 'topic' with a description. The description adds value by listing example topic values and explaining that omitting the parameter returns a full cross-category spread.

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 returns category-bucketed example questions about what Pipeworx can do, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx by focusing on suggesting questions rather than answering 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 explicitly states when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides example queries 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?

Describes the key behavioral nuance: row is deactivated (not deleted) so historical events remain via recent_alerts. Annotations already indicate idempotent and non-destructive, and description adds valuable 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?

Two sentences, front-loaded with action and ownership, second sentence explains 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?

For a simple, idempotent mutation with one parameter and no output schema, the description covers purpose, constraint, and effect completely.

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

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

Schema has 100% coverage for the single parameter 'id'. Description mentions 'by id' but adds no new meaning beyond the schema's description.

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

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

Clear verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings 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 enforcement ('only cancel your own subscriptions'), providing clear context. Lacks explicit alternatives or when-not-to-use, but sufficient for a simple mutation.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate safety and idempotency. The description adds significant behavioral context: the two-path routing (structured vs. grounded), the return format (verdict, value with citation, reasoning), and tolerance behavior. No contradiction.

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

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

The description is appropriately sized for the tool's complexity, front-loaded with examples and key phrases. Every sentence adds value, covering purpose, usage, behavior, and parameters with no redundancy.

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

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

Despite no output schema, the description fully explains the return values (verdict types, actual value with citation, reasoning). It covers parameter details, routing logic, and tolerance, making the tool's behavior completely understandable.

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

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

Schema description coverage is 100%, but the description adds value beyond the schema by clarifying the natural-language nature of the 'claim' parameter, the default and override behavior of 'tolerance_pct', and the internal routing logic.

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: to verify factual claims against authoritative sources. It provides specific verb phrases ('fact check', 'verify the claim') and distinguishes itself from siblings by noting it replaces 4-6 sequential calls.

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 guides when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It details the two paths (SEC EDGAR for company financials, grounded pipeline for others) but does not explicitly mention when not to use it or compare with sibling tools.

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