Healthdata

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds transparency by detailing the return format (per-model scores combined view), default model, and the need for a separate API key for Anthropic calls. 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 concise (two sentences) and front-loaded with the core purpose. Every sentence adds value: first sentence explains action and default, second covers optional probing with BYO key and return format.

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

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

Given the complexity (4 parameters, no output schema), the description adequately explains the return structure (per-model fields + combined view) and typical use cases. It does not cover edge cases or error behavior, but it is sufficient for effective use.

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

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

Schema description coverage is 100%, but the description adds value by explaining the default model behavior, optionality of 'models' array, and the purpose of '_apiKey' (only needed for Anthropic) and 'context' (disambiguation). These are not present 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?

The description clearly states the tool's action ('Probe one or more LLMs') and resource (knowledge about a business/brand/product/topic) with a specific output (visibility score 0-100). It distinguishes itself from sibling tools like 'compare_entities' by focusing on AI visibility scoring.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context on default model and optional API key. It does not explicitly state when not to use or compare with alternatives, but the usage context is clear.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive traits. The description adds valuable context beyond that: it routes to a vast number of tools, returns structured answers with stable citation URIs, works on all tiers, and is fast. It does not contradict annotations. The added details about routing and citations justify a score above the baseline.

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 densely packed with essential information: usage priority, trigger phrases, examples, alternative tool naming, and routing behavior. It is front-loaded with the 'PREFER OVER WEB SEARCH' directive. While it could be slightly trimmed, every major clause serves a purpose for a default entry-point tool.

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

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

This is a complex routing tool with only one real parameter and no output schema, so the description carries the full burden—and it succeeds. It explains the tool's purpose, scope, behavior, examples, and when to escalate to alternatives. An agent has everything needed to decide whether to invoke this tool and what to pass.

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

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

Schema description coverage is 100%: all six parameters are documented, with 'question' receiving a full description and aliases listed. The description itself does not add parameter-specific semantics beyond what the schema already provides, so the 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 a specific function: routing questions to 5,462 tools across 1,419 sources and returning structured answers with pipeworx:// citation URIs. It distinguishes itself from sibling tools by explicitly naming ask_pipeworx_grounded and deep_research as step-up alternatives, and frames itself as the default entry point for factual queries.

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: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is' and 'look up', and concrete examples. It also clearly explains when not to use it and which alternatives to choose: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This is exemplary usage guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains the beta status, that improvements are enabled live during tests, that currently no candidate is active and it matches ask_pipeworx exactly, and that it falls back to nothing (it is a full working router). This is transparent about experimental variability.

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

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

The description is well-structured and each sentence earns its place, but the first sentence is quite long and packs multiple facts. Overall efficient and front-loaded, though it could be tightened slightly without losing meaning.

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

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

The description covers purpose, usage, experimental behavior, and current state well. It references 'same response shape' implying output matches ask_pipeworx, which is sufficient given siblings exist. It does not describe return values, but with no output schema and by deferring to ask_pipeworx, completeness is adequate.

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

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

Schema coverage is 100%, with each parameter (including aliases) already described in the schema. The tool description adds no additional meaning to the parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states this is a beta router identical to ask_pipeworx, with the same tools and arguments. It explicitly distinguishes itself as the experimental edge version, which sets it apart from the stable sibling ask_pipeworx.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', giving clear when-to-use context and indicating an alternative (stable router). However, it does not mention other siblings like ask_pipeworx_grounded or provide explicit when-not-to-use conditions.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses the exact return shape with {answer, evidence, confidence, source, fetched_at, refusal_reason}, lists all possible refusal reasons, and explains the extra LLM call cost. This gives agents a complete behavioral model without any contradiction.

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

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

The description is appropriately sized and front-loaded: it opens with the core purpose, then details mechanism, return format, usage, and cost trade-off. Every sentence earns its place with no redundancy, making it a model of efficient technical communication.

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

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

Despite having no output schema, the description fully specifies the success and refusal return structures, including refusal reasons and context for use. It also addresses cost and alternatives, leaving no essential decision-making information missing 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?

The input schema already documents all six parameters with 100% coverage, including aliases for the question parameter. The description does not add parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts the answer') and resource ('tool result contains'). It explicitly differentiates from ask_pipeworx by emphasizing grounded extraction and refusal behavior, making it distinct among siblings.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' with concrete domains (financial, legal, medical, public statements). It also provides an explicit alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, covering both inclusion and exclusion.

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

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

The description extensively details behavioral aspects beyond annotations: resolver contract with confidence levels, parent event extraction, news fallback fields, low-confidence short-circuit, closed market handling, wide-spread market warnings, and cancellation rules. This far exceeds the basic readOnly/idempotent hints provided in annotations.

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

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

The description is long but well-structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.). It front-loads the core purpose in the first sentence. For a complex tool, the length is justified, though some redundancy exists (e.g., repeating classification examples).

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

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

Given the tool's complexity (multiple classifiers, response shapes, safety checks, cancellation rules), the description is remarkably complete. Since there is no output schema, the description fully covers return fields and edge cases, making it self-sufficient for an agent to understand the tool's behavior comprehensively.

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%. The description adds context to parameters: it explains the 'depth' parameter (quick vs thorough) and 'include_raw' parameter (full vs summarized payloads). However, the schema already describes these clearly, so the description's additional value is moderate but useful.

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 researches a Polymarket bet by pulling Pipeworx data. It specifies the input formats (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on specific strategies.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also includes classifier examples and fan-out examples. However, it does not directly state when not to use this tool or mention specific alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are sorted by primary metric, returns paired data with citation URIs, and clarifies data sources (SEC EDGAR/XBRL for companies handling off-calendar fiscal years, FAERS for drugs). No contradiction.

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

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

Description is packed with useful information and front-loaded with example queries. While comprehensive, it is slightly long but every sentence earns its place 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?

Covers purpose, usage, data sources, sorting behavior, and output format (paired data + URIs). No output schema exists, but description provides sufficient context for an agent to invoke correctly. Minor gap: exact output structure not detailed, but adequate.

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

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

Schema coverage is 100% with both parameters described. Description adds value by giving concrete examples (tickers for companies, drug names) and explaining what data each type pulls, going beyond the schema's enum and array 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 'side-by-side comparison of 2–5 companies or drugs' and provides example queries like 'compare X and Y' or 'X vs Y'. It distinguishes from sequential lookups, establishing a specific verb+resource+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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', indicating when to use. It also notes that it replaces 8–15 sequential lookups, offering strong usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description goes far beyond: 'never invented', 'gaps[] for facets the data couldn't answer', 'second-hop iteration', 'contradictions[]', 'citation_uri... always fetchable', 'semantically excerpted', and latency expectations (15-90s). It also discloses the paid tier requirement for 'thorough'. These are significant behaviors not captured by annotations.

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

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

The description is long and dense, but every sentence earns its place by adding operational detail (alternatives, depth behavior, return contract, latency, caveats). It is front-loaded with account requirements and scope. However, it is delivered as a single run-on paragraph without visual structure or bullet points, which can bury key guidance. Slightly reduced from 5 due to scannability, but the length is not gratuitous.

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 fully specifies the return contract: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', 'explicit gaps[]', 'contradictions[]', 'hop' field, and resolvable citation_uri. It also covers prerequisites, failure modes, latency, and depth iterations. For a complex tool, this is exceptionally 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 the schema already documents both parameters. But the description adds meaningful layer: it explains that 'question' can be broad/multi-part, and gives concrete values for depth ('quick=3', 'standard=5', 'thorough=8'), including the paid restriction and behavioral differences (gap recovery, contradictions scan). This adds semantics well beyond the enum labels.

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

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

The description states a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources', and clarifies 'this is NOT open-web search'. It explicitly distinguishes itself from sibling tools like ask_pipeworx and describes its decomposition and parallel routing behavior. This is far beyond a vague tautology.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also conditionally directs users without an account to ask_pipeworx, and explains depth-level trade-offs. This is a textbook example of usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This enriches behavioral 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?

Description is front-loaded with purpose and includes a usage tip and example domains. It is somewhat long but each sentence adds value. Could be slightly more concise but well-organized.

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

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

Given 6 parameters, no output schema, the description explains what the tool returns (top-N tools with schemas), when to use, and what domains it covers. It is fully adequate for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100% and description explains that 'query' accepts multiple aliases (task, q, search, description) and 'limit' is a number with defaults. It adds context that aliases are accepted, which schema lacks, but no extra parameter 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 'Find tools by describing the data or task', uses a specific verb+resource (discover tools), and differentiates from siblings by positioning itself as a discovery/browsing tool among many specific tools like search_datasets or entity_profile.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use and context, and implies not to use if you already know the tool.

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

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

Annotations already mark readOnlyHint=true, idempotentHint=true. Description adds valuable behavioral context: it makes a 'parallel call' across multiple sources, returns specific fields with URIs, and notes the patents limitation. 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?

Reasonably concise given complexity. Front-loaded with example queries. The detailed list of return fields is informative but slightly verbose. Could be tightened 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 (multi-source aggregation) and no output schema, the description fully covers what the tool does, its limitations, and expected return structure. 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%, and description adds substantial meaning: provides examples (ticker 'AAPL', zero-padded CIK), clarifies that names are not supported, and explains the 'type' parameter only supports 'company'. This goes well 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 ('Tell me about', 'research', 'brief me on') and clearly states it provides a 'full cross-source profile of a US public company'. It lists specific outputs (SEC, XBRL, patents, news, LEI) and distinguishes itself from sibling tools by stating it should be preferred over chaining single-pack lookups for holistic views.

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 ('ALWAYS PREFER...when the user asks for a holistic view') and when not ('names not supported – use resolve_entity first'). Also clarifies that patents soft-fail due to API sunset. The 'ALWAYS PREFER' directive provides strong usage guidance relative to 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 destructiveHint=true and idempotentHint=true. The description adds no behavioral context beyond these, merely restating the deletion action. With strong annotation coverage, the description adds little extra value.

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

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

Two sentences, front-loaded with the core purpose, each sentence earning its place. 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 single-parameter destructive tool with no output schema, the description covers all essentials: what it does, when to use it, and how it relates to sibling tools.

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

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

Schema coverage is 100%, and the schema already describes the 'key' parameter as 'Memory key to delete'. The description does not elaborate on valid key formats or validation rules, so it adds no 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 explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It directly distinguishes from sibling tools by naming '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?

Provides clear guidance on when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with remember and recall, giving context.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the process: fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This context goes beyond the annotations without contradiction.

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

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

The description is a single paragraph of about 5 sentences, front-loading the main purpose and then providing details and use cases. It is efficient and easy to parse, though it could be slightly more concise 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?

Given the tool's simplicity (2 params, no output schema) and the rich annotations, the description covers the purpose, process, output format, and use cases. It lacks error handling details, but for a non-destructive, read-only tool, it is sufficiently complete for an agent to use correctly.

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

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

With 100% schema coverage for the two parameters ('url' and 'max_links'), the description does not add additional meaning beyond what the schema already provides. It mentions the output format but does not elaborate on parameter usage or constraints, so a 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 clearly states the tool generates an llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt'. It also distinguishes itself from sibling tools by focusing on AI crawler indexing, which none of the siblings (like 'ai_visibility_check' or 'scan_competitor_ai_presence') directly address.

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

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

The description explicitly lists three use cases: client site indexing, personal project drafting, and competitor auditing. While it does not mention when not to use the tool or contrast with alternatives, the use cases are clear and cover the main scenarios, providing good guidance for an AI 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 declare readOnlyHint, idempotentHint, etc. Description adds specific return fields (title, description, organization, resources, etc.) providing extra context beyond annotations.

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

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

Two sentences, no fluff, clear and front-loaded with 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?

Simple tool with one param and output schema; description covers key aspects. No gaps.

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

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

Schema coverage is 100%, but description adds value by stating the ID comes from 'search_datasets', aiding correct invocation.

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

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

Description uses specific verb 'Get' and resource 'full metadata for a HealthData.gov dataset by its package ID.' It lists return fields, differentiating it from sibling 'search_datasets' which presumably returns a list.

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?

Implies when to use: when you have a specific package ID and want full metadata. Not explicitly exclusive but clear usage context given 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 provide readOnlyHint=true, destructiveHint=false, etc. Description adds return field specifics and clarifies 'active subscriptions' default behavior, but safety profile is already covered.

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 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?

Complete for a read-only list tool. Annotations cover safety, description covers purpose, return fields, and usage guidance. No output schema needed since fields are listed.

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% (single parameter with description). Description adds minimal extra context ('active subscriptions' default), but schema already does heavy lifting.

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

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

Description clearly states 'List the caller's active subscriptions' and lists return fields (id, type, params, etc.). It distinguishes from siblings '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 guides when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context and excluded reasons.

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 and offer minimal safety signals. The description adds meaningful behavioral context: rate-limited to 5 per identifier per day, does not count against quota, and is read daily by the team, which helps agents set expectations. No contradiction.

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

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

The description is lengthy but each sentence carries operational value, including exclusions, formatting guidance, and rate limits. It is front-loaded with the core purpose and stays organized, though it could trim minor redundancy.

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

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

For a feedback tool with no output schema, the description covers the full context: purpose, usage, exclusions, content expectations, and operational limits. Return values are likely trivial, so no output explanation is needed.

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

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

All parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds one useful guideline: describe issues in terms of Pipeworx tools/packs and don't paste end-user prompts, enriching the `message` field semantics.

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

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

Description opens with a specific, actionable purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling research/query tools by scoping feedback to Pipeworx tools only and explicitly stating other MCP servers are out of scope.

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

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

The description provides explicit when-to-use triggers (bug, feature/data_gap, praise) and an explicit when-not-to-use with an alternative: 'file it with that server instead' for tools from other MCP servers. This fully addresses usage guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable context: data is self-aggregating from CF analytics-engine, no PII, cached 5min to 1h. This goes beyond annotations and sets proper expectations.

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 functionality, followed by bullet-point use cases and additional details. Each sentence contributes meaning, though it could be slightly tighter.

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

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

Given no output schema, the description clearly explains what is returned (top tools, packs, volume) and covers the data source, caching, and parameter behavior. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds minimal extra value beyond what the schema already provides, so a 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 clearly states the tool's purpose: returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and nouns, and distinguishes itself from siblings by focusing on trending data aggregated from other AI agents.

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?

Three explicit use cases are provided, explaining when to use the tool. It also differentiates between shorter and longer windows for different needs. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description adds significant behavioral details: scanning top ~200 markets, partition checks, semantic anchor for similarity, placeholder filtering, fill check against CLOB depth, and output structure. 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 detailed and well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but is somewhat long and dense. Every sentence adds value, but could be slightly more concise for an AI 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?

Despite no output schema, the description explains the response format (opportunities[], partition_check) and trade signals. It covers modes, edge cases (placeholders, low similarity), and ties into fill risk. Annotations provide safety context. The description is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100%, and the description adds depth: explains what event slugs and topic strings look like, gives examples, and describes how each parameter affects behavior (single-event vs cross-event). This goes beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and provides specific use cases.

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

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

The description explicitly guides when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It recommends the event mode for a specific market. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_fill_risk, leaving some ambiguity.

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 set readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond these by detailing caching (1h at KV level), the five model families and three response segments, edge calculation details (slippage, Kelly fractions, spread filters), and diagnostic fields. It also explains the 'Fed note' exclusion and tradeable-edge knobs.

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

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

The description is quite long (over 600 characters) and includes extensive technical details about model families, edge calculation, and diagnostics. While it is front-loaded with the main purpose, the verbosity could be trimmed. It uses inline formatting with parentheses and dashes but lacks clear section breaks.

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

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

Given the tool's complexity (9 parameters, no output schema, rich annotations), the description covers all necessary information: the output structure (by_segment segments, diagnostics), the edge calculation methodology, caching behavior, and the purpose of each knob. It compensates well for the lack of an output schema by describing the response top-level fields.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema for parameters like category_filter (explaining how to combine segments) and min_partition_leg_kelly (explaining why min_kelly doesn't filter partition arbs and what this knob does instead). Some parameter descriptions in the description are redundant with the schema, but overall it adds 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 that the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifically built for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge discovery across multiple model families and providing a ranked output.

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

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

The description explicitly states the primary use case (discovering betting opportunities) and provides guidance on how it works (scanning top markets without paging). It also notes that Fed bets are excluded from ranking due to unreliable signal. However, it does not explicitly mention when not to use this tool or suggest 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?

The description adds significant behavioral context beyond annotations: it details the three response arrays (tracked, expired, snapshot_dates) with field semantics, explains that decay is computed on absolute edge value with signed direction, and notes limitations (60-day TTL, daily closes, not intraday). Annotations already indicate readOnly and idempotent, and description does not contradict any annotation.

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

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

The description is front-loaded with the core purpose and then details the response structure. It is somewhat lengthy but every sentence provides value, explaining edge cases (gaps in snapshots, median lifespan). It could be slightly more concise 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?

Given no output schema, the description fully describes the response structure with field names and meanings (tracked, expired, snapshot_dates, first_seen, trend, decay_pp_per_day, lifespan_days, etc.). It also covers limitations (snapshot TTL, decay basis). For a tool with two optional parameters, the description is very complete.

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

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

The input schema has 100% coverage with descriptions for both parameters (days, window). The tool description reaffirms defaults and clamping but does not add new semantics beyond the schema. Per rubric, high schema coverage yields a baseline of 3; the description does not warrant a higher score as it adds minimal 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 answers 'how long has this edge existed and is it shrinking?' and explains the distinction between a fresh wide edge and an old one. It uses specific verbs (edge persistence and decay telemetry) and distinguishes from sibling tools like polymarket_edges by focusing on time-series and decay.

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

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

The description gives explicit guidance on when to use the tool: to assess edge persistence and decay, with concrete examples. It does not explicitly state when not to use it, but context from sibling tools (e.g., polymarket_edges for raw edges) provides indirect guidance. A clear 'when to use' is present, but 'when not to use' is implied rather than stated.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context beyond annotations: walking the order-book ladder, returning specific metrics (vwap_fill_price, slippage_pp, verdict), and highlighting that partial basket fills convert arb into unhedged directional positions – a key risk. No contradiction.

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET) and uses bold for key terms. While somewhat long, every sentence adds value. Minor deduction for length; could be slightly tighter but remains highly functional.

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

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

Despite having no output schema, the description comprehensively lists all return values for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, profit_usd, forced_directional_risk). It covers edge cases (thin books, partial fills) and states the dominant loss mode. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant meaning: explains modes (single-market vs basket), default values, interpretation of size_usd (max spend vs target proceeds vs settlement notional), and details per-mode parameter usage. This compensates for any schema brevity.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live order-book depth. It distinguishes between single-market and basket modes with specific verbs (check edge, compute fill details) and resources (market, event). It differentiates from sibling tools like polymarket_arbitrage by recommending use before acting on their signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also implies when not needed (small trades) and warns about risks of partial fills, providing clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: compatibility_warning conditions, temporal alignment checks, skipped cross-type/subtype counters, and the fact that the delta is only meaningful when bet shapes are equivalent. 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 slightly long but well-structured with clear sections (modes, response, safety fields). It is front-loaded with the purpose and each sentence adds information. Could be 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?

No output schema, so the description fully covers the response format: leg-by-leg prices, matched spreads, safety fields (compatibility_warning, temporal_alignment, skipped counters). Given the tool's complexity, this is comprehensive and 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% with parameter descriptions. The description adds value by listing the 10 topic shortcuts and explaining that explicit parameters override the topic mapping. This goes beyond the schema, justifying above baseline 3.

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+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings like 'polymarket_arbitrage' by focusing on spread across venues and includes a compatibility check, making it unique and specific.

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

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

The description explains two modes ('topic' and explicit) and warns that most pre-mapped topics return compatibility warnings, implying when the tool may not be useful. It does not provide explicit alternatives or 'when not to use', but the guidance is clear enough to avoid misuse.

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 scoping details (identifier-based) and the behavior when key is omitted, beyond annotations that already state readOnly and idempotent.

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

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

Three concise sentences, front-loaded with the main action, no wasted words.

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

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

No output schema, but description adequately implies return values. Sufficient for a simple retrieval tool with good annotations.

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

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

Schema has 100% coverage with a clear description. Description repeats and clarifies the omission behavior, adding slight extra value.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys, using a specific verb and resource. It distinguishes from sibling tools 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 'Use to look up context the agent stored earlier' and mentions scoping. Does not explicitly state when not to use, but context makes it 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 will flag events as read, implying a write operation. However, annotations declare readOnlyHint=true, contradicting this behavior. This significantly harms 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 concise, with every sentence adding meaningful information. It is well-structured, front-loading purpose, then payload details, filtering, side effects, and alternatives.

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

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

The description covers purpose, return payload, filtering, side effects, and alternative access methods. It lacks information on error handling or pagination, but given the tool's simplicity and annotations, it is mostly complete.

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

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

Schema coverage is 100%, and the description adds value by providing concrete examples (e.g., type 'sec_8k') and explaining the effect of mark_read on future calls, which the schema alone does not convey.

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 'Pull fired events from your subscription feed' with clear verb+resource. It specifies the return payload and filtering options, making it distinct from sibling tools like 'list_subscriptions' or 'recent_changes'.

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

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

The description provides context for usage, mentioning polling and an alternative REST endpoint for scripts/dashboards. It does not explicitly exclude sibling tools, but the tool's purpose is well-defined for reading recent alerts.

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

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

Discloses fan-out to multiple sources, fallback behavior, soft-fail for USPTO, and return structure. Annotations already indicate read-only, idempotent, non-destructive; description adds significant 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?

Single paragraph with logical flow, but slightly lengthy. Every sentence adds value, but could be trimmed slightly.

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

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

Completely explains tool behavior, inputs, outputs, and alternatives, compensating for lack of output schema.

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

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

Adds meaning beyond schema: explains since format with examples, recommends default, clarifies value types, and confirms type enum restriction.

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

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

Description clearly states the tool returns a change feed for a company across multiple sources, provides example queries, and distinguishes from entity_profile.

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

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

Explicit when-to-use guidance with example queries, and when-not-to-use by recommending entity_profile for static profiles.

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 it's a write operation with idempotentHint=true. The description adds scope (key-value by identifier), persistence details (authenticated vs anonymous), and mentions pairing with recall/forget. 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 concise, well-structured, and every sentence adds value. It front-loads the core purpose and efficiently covers usage, behavior, and pairing.

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

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

Given no output schema, the description thoroughly covers purpose, usage, parameters, behavioral traits, and context. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with clear descriptions. The description adds example values like 'subject_property' and 'target_ticker', providing extra guidance beyond the schema.

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

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

The description clearly states the verb 'save', resource 'data', and context 'across this conversation or across sessions'. It distinguishes from siblings by mentioning 'recall' and 'forget' later.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. It also suggests pairing with recall/forget. However, it does not explicitly state when not to use or provide alternatives beyond the mentioned 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 readOnly/idempotent/non-destructive. The description adds that it cascades through several lookup endpoints, auto-disambiguates input, and returns citation URIs, giving operational context beyond safety flags.

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 informative but lengthy, covering two entity types with examples, return details, and citation URIs. It is front-loaded with examples and use cases, but is not as concise as the two-sentence ideal; however, every sentence contributes necessary information.

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

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

Given no output schema, the description fully describes return values (ticker, CIK, company_name, RxCUI, etc.) and citation URIs, making it complete for selecting and trusting the 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 descriptions for both parameters. The description adds examples and notes auto-disambiguation for company inputs, illustrating accepted formats beyond the schema's bare enumeration.

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 a user-spoken name to the canonical/official identifier, with concrete examples like 'What's the ticker for…' and 'find the CIK for…'. It differentiates by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use context. It also explains that it replaces 2-3 manual lookups, reinforcing its role.

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. The description adds behavioral details: it probes each entity with ai_visibility_check, uses first entity as subject, returns ranked list with score/confidence/signal density. No contradiction with annotations.

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

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

Three sentences: first states core function, second explains mechanism, third gives use case and output. Concise, front-loaded, no fluff.

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

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

Despite no output schema, the description clearly states return format (ranked list with score/confidence/signal density). It covers all required aspects and optional parameters. Sufficient for a read-only comparison 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 baseline 3. The description adds value: explains 'entities' are brand names with first as subject, clarifies 'models' probe options, describes '_apiKey' condition, and 'context' disambiguation. This goes 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 compares AI visibility across multiple entities side-by-side, ranks them, and identifies most/least recognized. It distinguishes from sibling tool ai_visibility_check by specifying multi-entity comparison and ranking.

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

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

The description gives concrete usage context ('competitive AI-marketing audits') and implies when to use (comparing multiple brands). It does not explicitly exclude alternatives, but the purpose 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?

Adds substantial behavioral details beyond annotations: fans out across two sources, returns specific fields, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. All consistent 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?

Front-loaded with purpose, but somewhat verbose with detailed return field listing and timing caveats. Every sentence adds value, but could be slightly more compact.

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, partial failures), no output schema, and rich annotations, the description fully covers when to use, what it returns, edge cases (timeouts, ecosystem scope), and behavior. An agent has sufficient context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor context about scoped packages and version defaulting, but does not significantly enhance understanding beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, combining data from deps.dev and bundlephobia. It uses a specific verb (scan) and resource (dependency), and distinguishes from sibling tools by its unique 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also mentions NPM-only scope and partial failure behavior. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a strong baseline. The description adds beyond by specifying the return fields (titles, descriptions, organizations, resource links), which clarifies the output structure without contradicting annotations.

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

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

The description is a single, well-structured sentence with relevant examples. It conveys the purpose and output in a compact form with 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 that an output schema exists, the description does not need to detail return values. It mentions the key return fields and the source. For a simple search tool, this is sufficient, though it could hint at pagination or result limits.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides keyword examples that align with the query parameter but does not add meaning beyond the schema's description. It is adequate but not exceptional.

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 searches HealthData.gov for public health datasets by keyword, which distinguishes it from sibling tools like search_within or deep_research that target different sources or types of data. The specific verb 'Search' and resource 'HealthData.gov' make the purpose unambiguous.

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

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

The description implies usage for searching public health datasets by keyword, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., search_within or bet_research). There is no mention of exclusions or conditions, leaving the agent to infer from context.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars' and mentions truncation and verification via offsets. 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 well-structured paragraph: purpose, when to use, pairing with alternative, then technical details. It is concise and front-loaded, though some redundancy could be trimmed (e.g., 'returns only the passages that matter' is implied by previous sentence).

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

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

Given the tool has 3 parameters, no output schema, and annotations covering safety, the description covers purpose, usage, technical details (embedding model, chunking, character limit), and pairing with another tool. The agent has sufficient information to decide and invoke the tool correctly.

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

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

The input schema already has 100% description coverage for all three parameters. The description adds concrete examples for text ('e.g. a SEC 10-K body') and query (examples like 'supply-chain risk'), and specifies default and range for limit, enhancing 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 'Semantic search INSIDE a fetched record,' specifying the verb (search) and resource (a fetched record, e.g., SEC filing or article). It distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded and noting that it's used when 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 context: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded.' It gives an alternative tool for grounding, but does not explicitly state when not to use this tool, though it is implied.

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

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

Disclosures beyond annotations: subscription creation is a write operation (consistent with readOnlyHint=false), returns ID, requires specific account type, mentions rate limits (10/day SMS), and webhook signing secret returned once. 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?

Dense but well-structured with clear topic sentences. Could be slightly more concise or organized into bulleted sub-sections, but front-loads the main action and progresses logically.

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 almost all aspects: creation, types, delivery, requirements. Lacks explicit return format for non-webhook deliveries, but consistent with no output schema. Persistent feed mention helpful. Highly complete for a complex tool.

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

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

Schema coverage is 100%, and the description adds significant value: explains type-specific params with examples, delivery constraints (verified phone, email pattern, webhook restrictions), and default feed. Enhances schema significantly.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying creation. Examples of supported types and delivery channels reinforce purpose.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types with examples, and delivery options. Implicitly distinguishes from alternatives like list_subscriptions. Could be more explicit about when not to use or prior setup like phone verification, but overall adequate.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by detailing output structure (category-bucketed questions with tool+argument shapes) and behavior differences between no arguments and topic parameter. 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 somewhat verbose but front-loaded with natural language questions that help match user intent. Every sentence is informative, and the structure is logical: intent, behavior, parameter 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?

For a simple tool with one optional param and no output schema, the description covers all needed context: what it returns, when to use it, how to parameterize, and its role in the tool ecosystem. No gaps.

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

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

Schema coverage is 100% with one param described. The description adds meaning beyond the schema: explains the purpose of the topic param ('focus area'), provides example values, and clarifies that omitting it gives a cross-category spread.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx. It uses specific verbs ('returns') and resources ('example questions') and distinguishes from siblings by positioning it as the onboarding entry point, unlike 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' and explains how to call with or without topic. While it doesn't list explicit alternatives, the context and sibling list provide sufficient guidance.

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

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

Explains deactivation instead of deletion and references 'recent_alerts' for historical events. Complements annotations (destructiveHint=false) without contradiction.

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

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

Two sentences with no waste. First sentence states purpose and constraint, second adds behavioral 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?

Low-complexity tool with full schema and annotation coverage. Description covers ownership and deactivation, sufficient for operation.

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

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

Schema covers 100% of parameters; description adds that id comes from 'subscribe' function, providing source 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?

Specific verb 'cancel' with resource 'subscription' by id, clearly distinguishing from '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 to cancel your own subscriptions with ownership enforcement; implicit when-not by exclusion, but no explicit alternatives given.

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

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

The description adds rich behavioral detail beyond annotations: return verdict types, citation format, reasoning, and replacement of multiple calls. No contradictions with annotations (readOnly, openWorld, idempotent, not destructive).

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

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

The description is comprehensive but slightly verbose. It front-loads keywords and examples effectively. Each sentence adds value, but could be tightened 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?

Given 2 parameters with full schema coverage, no output schema, the description covers all necessary aspects: use case, behavior, return structure, and edge cases. It is complete for an agent to decide and invoke correctly.

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

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

Both parameters are described in the schema (100% coverage). The description adds context: examples for claim, default tolerance behavior and range for tolerance_pct. Could be improved by stating the default tolerance_pct more explicitly.

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 verifies factual claims against authoritative sources, with specific examples and two distinct verification paths. It distinguishes itself by covering both structured financial claims and general claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes two pipelines but does not mention when not to use it or provide explicit alternatives among the listed sibling tools.

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