Revternal

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by detailing the output structure (per-model score, confidence, signals, raw_response, combined view) and the optional API key use, which aids transparency.

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 efficiently convey purpose, default behavior, optional key use, and use cases. Front-loaded with key information, no redundant phrases.

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

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

For a read-only probing tool with 4 parameters fully described and a clear output structure given, the description is complete. No output schema is needed as the return format is explained.

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%, yet the description enriches each parameter with examples and context (e.g., entity examples, model support, context disambiguation). This goes beyond the schema alone.

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

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

The description clearly states the verb ('probe'), resource ('LLMs', 'visibility score'), and scope ('per model'). It effectively distinguishes the tool from siblings by focusing on AI visibility assessment, not generic queries or research.

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

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

The description provides specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey for Anthropic. While it lacks explicit 'when not to use', the context is clear enough for an agent.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: routing to 5,093 tools, returning structured answers with citation URIs, working on every tier, and being a single fast call. 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 comprehensive yet every sentence adds value. It front-loads the priority instruction, then systematically covers routing, usage examples, and sibling differentiation. No unnecessary words.

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

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

Given the tool's role as a gateway to many sources, the description covers what it does, when to use it, what it returns (structured answer with citations), and how it relates to siblings. No output schema exists, but the description explains the return sufficiently. Complete for this type of query 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?

All six parameters are aliases for 'question', fully described in the schema (100% coverage). The description adds examples of what to ask and confirms natural language input, but does not add much beyond the schema. The examples provide extra clarity, earning a 4.

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

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

The description clearly specifies the tool routes factual questions to a large set of authoritative sources. It uses specific verbs like 'ask', 'look up', 'find', and explicitly distinguishes from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description starts with 'PREFER OVER WEB SEARCH' and provides explicit guidance on when to use this tool versus alternatives, including detailed examples and a decision hierarchy. It states 'START HERE for most questions' and clarifies when to step up to other tools.

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

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

The description adds significant value beyond annotations by detailing the beta nature, experimental routing improvements, fallback behavior (none), and comparison to the stable router. No contradictions with annotations.

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

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

The description is front-loaded with key identity ('Beta version of ask_pipeworx') and every sentence adds value. It is slightly verbose but not wasteful.

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

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

For a beta tool with experimental features, the description covers purpose, usage, behavior, and parameter semantics adequately. It mentions that the response shape is the same as ask_pipeworx, compensating for the missing 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?

Input schema already describes all parameters as aliases for 'question' with 100% coverage. The description does not add any additional meaning beyond stating it accepts the same arguments as ask_pipeworx, which is implicit.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It distinguishes itself from siblings by specifying it is the experimental edge and comparing to the stable router.

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

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

The description explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and explains the source-preference ranking behavior. It does not explicitly state when not to use, but the context of being experimental is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it makes an extra LLM call, extracts answer only from tool result, returns explicit refusals with reasons, and details the return structure. 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 a single paragraph of about 100 words with key information front-loaded. It is concise, though could be slightly tighter, but overall 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?

Despite missing an output schema, the description compensates by detailing the return format (answer, evidence, confidence, etc.) and refusal reasons. The tool has complex behavior (multiple tools, extra call), and the description covers these aspects adequately.

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 all 6 parameters with descriptions (100% coverage). The description does not add meaning beyond 'Your question in natural language.' Baseline score of 3 is appropriate.

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

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

The description explicitly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from 'ask_pipeworx' by noting the extra LLM call and use case. It clearly specifies the verb (extracts answer) and resource (tool result).

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

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

The description provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to use: 'prefer ask_pipeworx for casual lookups.' This clearly differentiates from siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description goes far beyond by detailing: how the tool resolves markets, fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms (low-confidence short-circuit, closed market detection), wide-spread checks, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and bullet-like formatting. Essential information is front-loaded in the first paragraph. While every sentence earns its place, some details could be streamlined without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers: input formats, classification, fan-out examples per category, response fields (market, analysis, evidence), resolver contract with confidence and alternatives, parent event extraction, news fallback, safety checks, closed market handling, wide spread warnings, and cancellation rules. All scenarios an agent might encounter are documented.

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

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

The input schema has 100% coverage with descriptions for each parameter. The description adds value by explaining the effect of 'depth' (quick vs thorough) and 'include_raw' (summarized vs full payloads) beyond what the schema provides. Examples for 'market' parameter are included. However, the schema itself is already clear, so the description adds moderate extra meaning.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types, resolves the market, fans out to data, and returns an evidence packet plus comparison. The verb 'Research' distinguishes it from sibling tools like 'polymarket_edges' which focus on edge 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 explicitly advises when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples. While it doesn't explicitly mention when not to use it, the context is clear enough. A brief note on alternatives would elevate it to 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing that off-calendar fiscal years are handled correctly, results are sorted by primary metric, and citation URIs are returned. No contradictions with annotations.

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

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

The description is well-structured with examples first, then purpose, then details. It is packed with useful information but slightly verbose; however, every sentence contributes value. Front-loaded with example queries makes it easy to understand quickly.

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

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

Given there is no output schema, the description provides a reasonable overview of return data ('paired data + pipeworx:// citation URIs', sorted by primary metric). It covers both entity types and their data sources. However, it could be more explicit about the exact structure of the response, which might require additional clarification 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 descriptions for both parameters. The description elaborates on the meaning of each parameter, including data sources for 'company' (SEC EDGAR/XBRL) and 'drug' (FAERS, FDA approvals, trials) and specifies that values should be tickers/CIKs for companies and drug names for drugs. This adds significant 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 the tool performs side-by-side comparison of 2-5 companies or drugs, with specific example queries ('Compare X and Y', 'X vs Y', etc.). It differentiates from sibling tools like entity_profile by emphasizing that this tool should be preferred over sequential single-entity lookups.

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

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

The description provides explicit guidance on when to use the tool (comparing entities, head-to-head) and gives example natural language triggers. It explicitly states 'ALWAYS PREFER over sequential single-pack lookups', helping the agent choose this over alternatives like entity_profile.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description richly adds behavioral details: parallel decomposition, hop mechanism, gap recovery, contradictions, citation_uri, semantic excerpting, and expected latency (15-90s). 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 thorough but lengthy and includes some redundancy (e.g., gaps[] mentioned multiple times). It front-loads critical account info, but overall structure could be tighter. Adequate 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?

Given the high complexity and absence of an output schema, the description covers all necessary aspects: input requirements, behavior, output format (findings packet with evidence, confidence, source, contradictions, gaps), constraints (account, paid plan), and performance expectations. Fully sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds value by defining each depth level (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and explaining how question decomposition works, thus enriching the semantic understanding.

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

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

The description clearly states it performs grounded multi-source research across 1,340 structured data sources in one call, distinguishing it from siblings like ask_pipeworx (single lookup) and ask_pipeworx (live news). It specifies the core action and scope.

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

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

Explicitly tells when to use this tool (broad/multi-part questions over structured data) and when not to (single lookup → ask_pipeworx; breaking news → ask_pipeworx). Also notes account requirements and paid plan for 'thorough' depth.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No 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, well-structured paragraph that front-loads the core purpose. Every sentence adds value, covering usage context, input details, return format, and actionable next steps. No wasted words.

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

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

Given the tool's complexity (discovery meta-tool, 6 parameters with aliases), the description is complete: it explains what it does, when to use it, what it returns (including full schemas and examples), and how to call it. No output schema is needed as the return format is 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 description coverage is 100% (6 parameters all have descriptions). The description adds value by noting that multiple aliases (task, q, description, search) are accepted and providing example queries. It does not elaborate on each parameter beyond the schema, but the schema is already detailed.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA, etc.) and explains that it returns relevant tools with full schemas. It distinguishes itself from sibling tools by being the discovery meta-tool.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on when to use it and implies when not to (if you already know which 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?

The description discloses behavioral traits beyond annotations: it fans out across multiple sources, returns specific fields with details (e.g., recent_filings URIs, fundamentals sorted, patents soft-fail after sunset), and clarifies that bad inputs will fail. No contradictions with annotations.

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

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

The description is densely packed with valuable information, but it is somewhat long. It front-loads example queries and the key preference instruction. Every sentence adds value, though a more structured breakdown could improve readability.

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

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

For a 2-param tool with 100% schema coverage and no output schema, the description comprehensively explains what the tool returns (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and their formats. It covers edge cases like patent sunset and name unsupported. No gaps identified.

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 context like examples (AAPL, 0000320193) and the note that CIK must be zero-padded, and that names are unsupported. This goes beyond schema descriptions, justifying a score of 4.

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

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

The description explicitly states the tool's function: returning a full cross-source profile of a US public company in one call. It lists example queries, data sources, and output fields, clearly distinguishing it from siblings that would require chaining multiple 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 explicit when-to-use guidance ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it (names not supported, use resolve_entity first). This helps the agent select the tool appropriately.

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

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

Description adds context beyond annotations (clearing sensitive data). Annotations already indicate destructive and idempotent; description aligns and provides additional behavioral insight.

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

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

Two sentences, front-loaded with purpose, 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 single-parameter destructive tool with no output schema, the description fully covers purpose, usage, and pairing with siblings.

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

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

Schema coverage is 100% with clear description for 'key.' Description adds no further 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?

Clearly states 'Delete a previously stored memory by key,' specifying verb and resource, and distinguishes from siblings ('Pair with remember and recall').

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

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

Explicitly lists when to use ('context is stale, task is done, clear sensitive data') and pairs with alternatives ('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 indicate safe, read-only, idempotent behavior. The description adds 'fetches the page, extracts title/description/key links, and emits standard format', which provides useful behavior context beyond annotations. No contradiction.

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

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

Three sentences plus a bullet list of use cases. Front-loaded with main purpose, well-structured, and no fluff. Could be slightly more concise but effective.

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

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

Description explains input (URL), process (fetch & extract), and output (markdown text blob). With no output schema, it adequately describes what the agent can expect. Annotations cover safety. Could mention HTTP request dependency, but overall complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add extra meaning beyond the schema, which is acceptable per guidelines (baseline 3 for high coverage).

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

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

The description clearly states it generates an llms.txt file for any URL, with specific verb and resource. It distinguishes from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the actual file.

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 lists three concrete use cases (getting client's site indexed, drafting for own project, auditing competitor). It implies when to use but does not explicitly state when not to use or mention alternatives, though the sibling list provides options.

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. Description adds return fields and default behavior, but no new behavioral context.

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

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

Two sentences, no fluff, front-loaded with purpose and immediate guidance.

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

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

No output schema, but description lists returned fields adequately. Covers optional parameter and default behavior. Complete for a simple list 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 parameter already described. Description adds no further meaning beyond what schema provides.

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

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

Description clearly states 'List the caller's active subscriptions' with verb and resource. Distinguishes from sibling tools subscribe and unsubscribe.

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

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

Explicitly says to use before adding more subscriptions or to find an id to cancel. Implies when not to use, though no direct alternative named.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limits (5 per identifier per day), cost-free usage, and that it doesn't count against quota. It also explains how feedback is processed (digests, roadmap impact). No contradictions with annotations.

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

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

The description is five concise sentences, front-loading the purpose and then providing usage guidelines and constraints. Every sentence adds value without repetition or unnecessary detail.

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

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

For a simple feedback tool with 3 parameters (one enum, one nested object) and no output schema, the description covers all necessary context: when to use, content guidelines, rate limits, and quota impact. It is fully self-contained.

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

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

Schema coverage is 100%, so the schema already documents param details well. The description adds value by specifying message formatting (specific, 1-2 sentences, 2000 chars) and reinforcing the enum meanings, but does not redundantly repeat schema info.

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: sending feedback about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell') and explicitly defines each feedback type, distinguishing it clearly from any sibling tools.

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

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

Provides explicit guidance on when to use each feedback type (bug, feature/data_gap, praise). Instructs users to describe issues in terms of tools/packs and to avoid pasting end-user prompts, ensuring effective communication.

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

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

Adds significant context beyond annotations: explains data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and idempotent nature. 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?

Concise and front-loaded with the core purpose. A few more sentences than necessary but each adds value. Could be slightly tighter without losing 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?

Adequate given the tool's simplicity and rich annotations. Lacks explicit details on the return format (e.g., structure of the list), but the description covers key aspects like caching and privacy. Missing output schema increases the burden slightly.

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 the parameter fully, but description adds valuable semantic guidance on window choice (hot vs steady-state). This enhances the schema's enum values.

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

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

The description clearly states the tool returns trending calls on Pipeworx, specifying outputs (top tools, top packs, total call volume) and time windows. It distinguishes itself from siblings like 'discover_tools' by focusing on current usage patterns rather than available 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 lists three concrete use cases for when to use the tool, along with guidance on window selection. However, it does not explicitly mention when not to use or direct users to alternatives among the sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds rich behavioral details: monotonicity violations, partition checks, semantic anchor (Jaccard similarity), partition filter, and fill check against live CLOB depth. No contradictions.

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

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

The description is dense but well-structured, covering all modes and edge cases. While slightly long, every sentence provides value. Front-loaded with main purpose.

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

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

Given the tool's complexity (2 params, no output schema), the description is extremely comprehensive. It explains all modes, edge cases, fill check, and even references another tool for custom sizing.

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 description adds examples of slugs, explains behavior per mode, and mentions fill check. It significantly enhances meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection and providing detailed methodology.

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 with NO args for trending scan, pass 'event' for per-event partition check, or 'topic' for cross-event scan. Recommends 'event' for specific markets and warns when not to trade (realizable_edge_pp ≤ 0). Mentions alternative tool polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds rich behavioral context: caching (1h KV-level), model details, diagnostic output, tradeable-edge knobs, and disclosure of Fed bet exclusion. This far exceeds annotation requirements.

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?

Despite length, every sentence earns its place. The description is front-loaded with purpose, uses structured enumeration of model families, and logically groups knobs. It balances technical depth with readability for an agent.

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

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

With no output schema, the description fully covers the response structure (by_segment, fed_candidates, _diagnostics) and explains how knobs filter output. It also notes caching behavior and limitations. For a complex 9-parameter tool, this leaves no critical gaps.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond parameter names and types. For example, min_kelly is explained as skipping too-small opportunities, and the relationship between min_kelly and min_partition_leg_kelly is clarified. Each parameter gains operational 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 the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from sibling tools by focusing on model-driven and structural arbitrage opportunities.

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 detailed guidance on when to use the tool (discover opportunities without paging), explains three model families, and mentions Fed bet exclusion. However, it does not explicitly state when not to use alternatives like polymarket_arbitrage, though context is strong.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing the response structure, limitations (60-day TTL, snapshot gaps, decay computation), trends, and expiry logic. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, then broken into clear sections for response structure and limitations. Every sentence adds value; no extraneous content.

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

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

Despite lacking an output schema, the description thoroughly explains all response fields (tracked[], expired[], snapshot_dates[]) and covers limitations, making it self-contained for an AI agent.

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

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

Both parameters are described in the schema (100% coverage). The description adds useful context like defaults and constraints (clamp 2-30, window family), enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking versus current snapshots.

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 on when to use the tool (to analyze edge persistence and decay) but does not explicitly state when not to use it or compare to alternatives. However, the context strongly implies appropriate usage.

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

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

Although annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior, the description adds critical behavioral context: it walks the order book ladder, returns detailed fill metrics, and warns about forced directional risk and thin books. This fully discloses the tool's behavior beyond just read-only safety.

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

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

The description is long but well-structured with clear labeled sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads the core purpose and then details modes. Slightly verbose but 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?

With no output schema, the description fully explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers error states (thin_legs, cannot_fill). It also explains edge cases like forced directional risk, making it complete for an agent to understand expected outputs and failure modes.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining the dual interpretation of size_usd (max spend on buys vs target proceeds on sells) and the default logic for side in basket mode. This provides helpful 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with explicit instructions for each. It leaves no ambiguity about the tool's function.

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

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

The description explicitly states when to use this tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the risks of not using it (partial fills leading to unhedged positions). It also provides guidance on mode selection based on input parameters.

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

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

Goes far beyond annotations by detailing response structure (leg-by-leg prices, spread[], top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and skipped counters. Explains two specific cases where compatibility warning fires, and what temporal aligned:false means. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Description is lengthy but well-structured with bolded section headers (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence adds necessary context for a complex tool. Some minor redundancy in explaining the compatibility warning but overall earns its length. Could be slightly trimmed while retaining clarity.

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

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

Covers all aspects needed: modes, response structure, safety fields, temporal alignment, skipped counters, and example values. Lacks output schema, so description fully compensates by explaining return data in detail. Complete for a data-analysis tool with complex compatibility logic.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description adds significant value by explaining the topic parameter with an exhaustive list of shortcuts, and explicates that kalshi_event_ticker and polymarket_event_slug override the topic mapping. Provides concrete format examples (e.g., 'KXFED-26OCT'). Exceeds baseline of 3 by adding interaction and overriding semantics.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, with two distinct modes (topic shortcuts and explicit tickers). Uniquely distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on cross-venue comparison.

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

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

Explicitly describes two usage modes and when to use each. Provides critical warnings: most pre-mapped topics return compatibility warnings, and explains conditions under which output should not be trusted (non-equivalent bet shapes, temporal misalignment). Includes explicit guidance on when not to treat results as tradeable.

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

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

Adds behavioral details beyond annotations: saving/retrieval pairing, listing behavior on omit, scoping. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and description enriches 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?

Three sentences, each with a clear role: purpose, examples, scope/pairing. No redundancy, front-loaded, efficient.

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

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

For a simple tool with one optional param and no output schema, the description fully explains behavior (with/without key), gives examples, and notes scoping and related tools. Sufficient.

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

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

Schema coverage is 100% and schema already describes the parameter. Description adds context on usage pattern (pair with remember/forget) and scoping, adding 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 retrieves values saved via remember or lists all keys, with specific use cases like ticker, address, notes. It distinguishes from siblings 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?

Explicitly says when to use (retrieve stored context) and pairs with remember/forget. Mentions scoping to identifier. Could include more explicit when-not-to-use, but context is clear.

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

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

The description states that setting mark_read:true flags events as read, implying a state mutation. However, the annotations declare readOnlyHint:true, which indicates no modifications. This is a direct contradiction, significantly undermining transparency.

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 earning its place: purpose first, then return format, then filtering/details, then alternative access. No wasted words.

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

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

Without an output schema, the description sufficiently describes return content (source, citation_uri, raw payload). It covers filtering, pagination (limit), mark_read behavior, and polling suitability. Minor gaps exist (e.g., error handling) but overall complete for typical 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?

The input schema already covers all 5 parameters with 100% description coverage. The description adds value by explaining the effect of mark_read and the filtering behavior 'Filter by type... and/or since', going beyond the schema's 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 'Pull fired events from your subscription feed' and specifies what each event carries (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions and subscribe by focusing on the actual event feed content.

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

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

The description provides explicit context: filter by type/since, set mark_read, and mentions polling suitability. It also gives an alternative (direct GET endpoint for scripts/dashboards). While it doesn't explicitly exclude sibling tools, the usage guidance is clear for this tool's purpose.

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, and destructiveHint false. The description adds significant behavioral detail: it fans out to multiple sources (SEC EDGAR, GDELT/GNews with fallback, USPTO with soft-fail), explains return structure (changes[], total_changes, URIs), and notes PatentsView API sunset. No contradictions with annotations.

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

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

The description is a single paragraph that packs extensive information efficiently. It is front-loaded with example queries. While comprehensive, it could be more structured (e.g., bullet points for sources) to improve scanability. Every sentence serves a purpose, but density slightly reduces 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?

Given the tool's complexity (multiple data sources, fallback logic, parameter formats), the description is remarkably complete. It covers all key behaviors, return structure, and distinguishes from sibling tool. No output schema exists, but the description adequately describes the return format. No gaps identified.

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

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

Schema coverage is 100%, but the description adds crucial context: explains `since` accepts ISO dates and relative shorthand with examples, recommends '30d' or '1m' for typical use, clarifies `value` can be ticker or CIK, and notes `type` is currently limited to 'company'. This 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 uses specific verbs and resources: 'change feed for a company', and lists example queries like 'What's new with X' and 'latest on Y'. It clearly distinguishes from sibling tool entity_profile by stating 'Use entity_profile instead when you want the static profile'. The purpose is unambiguous and differentiates from alternatives.

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

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

The description provides clear when-to-use guidance through example queries and parameter recommendations (e.g., 'Use "30d" or "1m" for typical monitoring'). It explicitly advises when to use the sibling entity_profile. However, it does not state when not to use this tool beyond that comparison, missing explicit exclusions.

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

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

Adds beyond annotations: explains scoping by identifier, persistence differences based on authentication, and 24-hour retention for anonymous sessions. 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?

Well-structured with front-loaded purpose and usage, but slightly verbose. Every sentence adds value; no waste.

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

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

Comprehensive for a save tool with two required params and no output schema. Explains storage, persistence, and sibling relationships. Could mention return value, but not critical.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds little beyond schema, but does mention key-value pair scoping. Baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse, specifies key-value pair resource, and distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use ('when you discover something worth carrying forward') and references alternatives ('Pair with recall... forget to delete').

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., and the description adds operational details: it cascades through multiple lookup endpoints internally and replaces 2-3 manual lookups. Also describes return formats. No contradiction with annotations.

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

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

Description is informative and well-structured, starting with example queries and then stating purpose, usage, and details. It is slightly long but every sentence adds value. Could be more concise but not wasteful.

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

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

For a tool with a simple input schema and comprehensive annotations, the description covers purpose, usage, return details, and efficiency. It does not mention error handling or edge cases, but those are not critical for this tool. Overall, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the return types for each enum value (company vs drug) and giving concrete examples for the value parameter (ticker, CIK, name), improving understanding beyond the schema's 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 resolves user-spoken names to canonical/official identifiers needed by other tools. It provides concrete examples and distinguishes itself from siblings by emphasizing it provides IDs that other tools require as input.

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 FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not explicitly mention when not to use, but the context implies that if you already have an ID, this tool is unnecessary. Could be improved by referencing alternative tools like entity_profile for deeper entity information.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by detailing the behavioral intelligence returned (work patterns, collaboration style, professionalism signals, etc.), which is consistent with annotations and provides useful context beyond the structured fields.

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 at ~70 words, front-loaded with purpose, then lists outputs, usage guidance, and an example. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description sufficiently enumerates the returned intelligence categories (work pattern, collaboration style, professionalism signals, activity recency). It also gives an example, making it easy for an agent to understand input and expected output. Tool has few parameters, so description is complete.

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

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

Both parameters are described in the schema (100% coverage). The description adds the example 'torvalds' for github_username and mentions that _apiKey is injected when omitted, but this largely repeats the schema description. No additional semantic enrichment beyond what schema provides.

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

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

The description uses a specific verb ('Get behavioural intelligence') and clearly identifies the resource (one developer by GitHub username). It lists the categories of returned data, distinguishing it from sibling tools like revternal_enrich_developer and revternal_search_developers.

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

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

It explicitly states when to use the tool: 'assess engagement, seniority signals, and outreach timing.' It provides an example call. However, it does not explicitly say when not to use it or list alternatives among siblings, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the detailed outputs (e.g., 'ranked skills breakdown') and providing a concrete example, which enhances understanding 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 extremely concise: two sentences and an example. Every sentence contributes meaning—purpose, outputs, and usage guidance. There is no fluff, and the key 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 lack of an output schema, the description adequately lists what the tool returns (name, location, company, etc.). For a read-only enrichment tool, this covers the agent's needs. However, it omits potential error conditions or rate limits, which are minor omissions for such a focused 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%, so the input schema already documents both parameters. The description does not add significant meaning beyond the schema; it repeats the github_url description and provides an example. The _apiKey injection is noted in the schema description, not in the tool description. Thus, baseline 3 is appropriate.

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

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

The description clearly states the verb 'Enrich' and the resource 'developer' from a GitHub URL, listing specific outputs (name, location, company, etc.). It distinguishes itself from siblings like `revternal_search_developers` by focusing on enrichment of a single known developer, though it does not explicitly differentiate from `revternal_developer_intel`.

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 to enrich a lead or candidate you already have a GitHub URL for.' It provides context but does not mention when not to use it or alternatives. The example further clarifies usage.

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

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

Annotations indicate readOnlyHint, idempotentHint, and not destructive. The description reinforces this by describing the output as static statistics with no side effects, adding context about what tools it supports (search results).

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

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

Two concise sentences front-loaded with the tool's purpose, followed by a concrete example. Every sentence provides 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?

For a simple statistics tool with no output schema, the description fully covers what the tool returns (profiles indexed, status) and its intended use. No gaps given the low complexity.

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

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

Schema coverage is 100% for the single optional parameter _apiKey, and the description includes an example call with empty arguments, reinforcing that no parameters are required. No additional parameter detail is needed.

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

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

The description clearly states the tool provides 'index statistics' including 'total profiles indexed and processing status' for the Revternal dataset. It is distinct from sibling tools like revternal_search_developers or revternal_developer_intel, which focus on search or enrichment.

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

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

The description explicitly says 'Use to gauge coverage and freshness before relying on search results', giving a clear use case. It does not list when not to use or alternatives, but the sibling context provides implicit differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds value by specifying exact return fields (GitHub username, role, language, location, last-active) and confirming the index is live. No contradictions with annotations.

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

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

The description is a single dense paragraph that conveys purpose, use cases, filters, return values, and pagination without waste. Could be slightly improved with bullet points or clearer separation of sections, 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?

Given 8 parameters (all with schema descriptions), no output schema, and rich annotations, the description covers core functionality, filter options, and pagination. Missing details on error handling or rate limits, but these are less critical for a non-destructive search 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 good descriptions, so baseline is 3. The description reinforces parameter meanings (e.g., active_within_days as 'only devs active in the last N days') and includes an example query that ties parameters together, adding moderate value.

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

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

The description clearly states the verb (search), resource (live index of ~11.7M GitHub-centric developers), and intended use cases (recruiting, GTM, research). It distinguishes from sibling tools like revternal_developer_intel by emphasizing broad search/filtering.

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 appropriate use cases (recruiting, lead-gen, audience research) and provides an example query. It lacks explicit guidance on when not to use it or comparison to alternatives, but the context signals (sibling tools) partially compensate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds that it probes via ai_visibility_check, ranks by score, and returns score, confidence, signal density. 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?

Three sentences with no fluff. Front-loaded with main action, then details and example. 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?

Covers behavior, parameter semantics, and use case. Lacks explicit return format details, but no output schema exists and annotations provide safety info.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: first entity is 'subject', explains _apiKey and context usage, and clarifies models default.

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 verb (compare, scan) and resource (AI visibility across multiple entities). Differentiates from sibling tools like ai_visibility_check (single entity) by emphasizing side-by-side comparison.

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

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

Explicitly mentions use case (competitive AI-marketing audits) and gives an example question. Implicitly contrasts with single-entity tools, but doesn't explicitly state when not to use.

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

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

Beyond annotations (readOnly, idempotent), the description adds details on fanning out across deps.dev and bundlephobia, return content (summary block, per-advisory detail, links, alternative versions), graceful degradation with sources_failed, and latency caveats.

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 informative but somewhat lengthy; however, it is well-structured with key points front-loaded (purpose, usage, return info). Every sentence adds value, with minor redundancy in listing 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?

Given no output schema and complexity (two services, multiple data points, partial failures, ecosystem constraint), the description thoroughly covers return format, failure modes, latency, and usage scope. No gaps identified.

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

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

Schema coverage is 100% (both parameters described). Description adds value by noting scoped packages are accepted and version defaults to latest, which are not in 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?

Description clearly states it is a composite check for evaluating npm packages, covering license, advisories, version history, bundle size, and ESM/tree-shake support. It uses specific verbs and distinguishes from siblings (other tools 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?

Explicitly tells when to use ('when an agent asks is X safe / popular / small') and when not ('NPM ecosystem only; other ecosystems go to deps.dev:version directly'). Provides context on partial failures and latency, but does not name a specific alternative sibling tool for non-NPM packages.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and character cap with truncation flagging. It also notes that passages include offsets for verification.

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, well-structured paragraph that front-loads the core action. Every sentence adds distinct value—purpose, usage context, technical details—with no redundancy or fluff.

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

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

Despite no output schema, the description adequately explains return values (top-N passages with offsets and scores). It covers the algorithm, constraints, and integration with sibling tools, making the tool fully understandable for an AI agent.

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

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

Schema coverage is 100%, but the description adds valuable context: examples for text (SEC 10-K, article) and query (e.g., 'supply-chain risk'), and clarifies limit defaults. This goes beyond the schema descriptions.

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

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

The description clearly states the verb 'search inside' and resource 'a fetched record'. It distinguishes from sibling tools by explicitly contrasting with ask_pipeworx_grounded and specifying use cases where the record is too large for the prompt.

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 guidance on when to use ('when the record is too big to cram into the prompt') and mentions pairing with ask_pipeworx_grounded. It does not explicitly state when not to use, but the context is sufficient.

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

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

Rich behavioral details beyond annotations: OAuth requirement, delivery channels (always-on feed, optional email/sms/webhook with constraints like SMS cap, phone verification, webhook signing details, auto-disable after 10 failures). 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 detailed but well-structured, front-loading the purpose then covering types, params, and delivery. Every part provides 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?

Covers purpose, parameters, delivery, prerequisites, and constraints completely for a creation tool. No output schema, but mentions return of subscription ID. Could mention how to manage subscriptions afterwards.

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

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

Schema has 100% description coverage, but description adds extensive context: explains each type with examples, provides required fields per params type, elaborates on delivery options with constraints (phone verification, SMS cap, webhook signing secret). Adds significant meaning beyond schema.

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

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

The description clearly states it creates a subscription to a live-data event stream and returns a subscription ID, with specific verb 'Create'. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Provides context on when to use (monitoring), prerequisites (OAuth account), and examples per type. However, lacks explicit comparison to alternatives like polling or when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds minor behavioral context (onboarding entry point, returns categorised questions) but does not significantly extend beyond what annotations already convey.

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 fairly long but front-loads the core purpose. Every sentence adds value, though it could be tightened without losing clarity. The use of alternatives and examples is helpful.

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 (1 optional parameter, no output schema), the description fully covers what the tool does, when to use it, and what it returns. No gaps remain.

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

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

Schema coverage is 100%, with a clear description of the optional topic parameter. The description adds a list of example values, but this is already implied by the schema. No additional meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It positions itself as the onboarding entry point, distinguishing it from siblings like ask_pipeworx or discover_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 says '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 context, though explicit exclusions or alternatives are not named beyond the implicit first-use scenario.

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

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

Adds behavioral context beyond annotations: describes deactivation vs deletion, and ownership enforcement. Annotations already provide idempotentHint and destructiveHint, and description aligns with them, providing useful nuance.

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: first states core action, second adds essential behavioral constraints. No unnecessary words, front-loaded purpose, 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?

Simple tool with one parameter, no output schema. Description covers ownership, deactivation, and persistence of historical events. Lacks error scenarios but adequate for the tool's complexity.

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

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

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Baseline 3 due to 100% schema coverage; tool description does not add new information beyond the schema.

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

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

The description uses specific verb 'cancel' and resource 'subscription' with clear identifier 'by id'. It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement and that only own subscriptions can be canceled. Mentions that historical events remain available via 'recent_alerts', hinting at an alternative. Lacks explicit when-not to use or direct comparison with 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 read-only, open-world, idempotent, non-destructive behavior. The description adds rich behavioral context: internal routing logic (structured vs. grounded), output structure (verdict, value, citation, reasoning), and performance benefit (replaces 4-6 sequential calls). 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 efficiently structured: opens with natural-language trigger phrases, then explains core functionality and processing paths, and ends with output details. Every sentence contributes necessary information without redundancy.

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

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

Despite lacking an output schema, the description fully covers return values (verdict types, actual value, citation, reasoning). With only 2 parameters and no nested objects, the description provides complete context for correct invocation.

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

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

Schema coverage is 100%, and the description adds significant value beyond schema: explains tolerance_pct overrides implied tolerance, default cap at 5%, and suggests 1-2% for hallucination detection. Provides concrete examples for the claim parameter.

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

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

The description clearly defines the tool's purpose: natural-language claim verification against authoritative sources. It provides multiple trigger phrases and explicitly states the two processing paths (company-financial via SEC EDGAR, other via grounded pipeline), distinguishing it from sibling tools like ask_pipeworx_grounded.

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 ('check whether something a user said is factually correct') and describes the two distinct verification paths with examples of claim types. Provides clear context without needing exclusions.

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