Jpl Ssd

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

Annotations already declare the tool read-only and idempotent. The description adds context: default model is free, Anthropic probing requires a BYO key with direct payment, and the return structure includes per-model details. This supplements 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 two sentences, front-loading the core action and outcome. Every sentence provides necessary information without redundancy.

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

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

Despite no output schema, the description enumerates return fields (score, confidence, signals, raw_response) and a combined view. Parameters are fully covered, and annotations provide safety assurances. The description is sufficient for an agent to use the tool effectively.

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 examples (e.g., 'Pipeworx', 'Acme Corp pricing') and clarifies the _apiKey parameter, but does not fundamentally extend beyond the schema definitions.

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

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

The description explicitly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It uniquely focuses on AI visibility auditing, clearly differentiating from sibling tools like ask_pipeworx or deep_research.

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

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

The description explains the tool's utility for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also clarifies when to provide an API key for Anthropic, but lacks explicit exclusions or comparisons to alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context by disclosing the routing behavior, argument filling, citation URI returns, and broad source coverage. It does not contradict annotations and enhances the agent's understanding of what to expect.

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

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

The description is long but every sentence earns its place: it front-loads the key 'prefer over web search' message, then delivers domain coverage, examples, alternative use cases, and escalation paths. The structure is logical and free of redundancy.

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

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

Despite having no output schema, the description compensates by specifying the return type ('structured answer with stable pipeworx:// citation URIs'), covering scheduling, mentions that it works on every tier, and lists numerous example queries. This is a complete contextual picture for an agent.

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

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

Schema coverage is 100% with all aliases described. The description enriches parameter semantics beyond the schema by providing realistic example questions ('current US unemployment rate', 'Apple's latest 10-K') that clarify the expected format and breadth of accepted input.

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

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

The description states a clear verb+resource: 'Routes the question to the right one of 5,529 tools across 1455 verified sources' and returns structured answers with citations. It distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for 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?

Provides explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'find') and concrete examples. Clearly says 'START HERE for most questions' and gives step-up criteria for alternatives, making the decision path unambiguous.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals the experimental nature, the current state (no active candidate, last retired on a specific date), and that results are compared against the stable router. This adds substantial behavioral context not inferable from annotations alone.

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

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

The description is well-structured and front-loaded with the beta status, then explains the current equivalence, usage, and caveats. Every sentence provides value, with no redundant or filler content. It is appropriately sized for the tool's complexity.

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

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

Given the tool's simplicity (single required param, no output schema), the description covers purpose, current behavior, usage guidance, and the absence of fallback. It mentions the response shape is identical to ask_pipeworx, so no output schema is necessary. Complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% with all parameters being aliases for 'question', each individually described. The description mentions 'same arguments' but adds no extra semantics beyond the schema. The baseline of 3 applies since the schema fully documents parameters.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with identical tools/arguments/response shape, and explicitly differentiates it from the stable version by mentioning candidate routing improvements. It names the sibling ask_pipeworx and provides a specific verb+resource description.

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

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

It explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies it is a full working router, not a fallback. This gives clear guidance versus the stable alternative and even explains the evaluation context (results compared to stable router).

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

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

The description discloses key behavioral traits beyond annotations: it requires an extra LLM call, returns verbatim evidence quotes, and can explicitly refuse with specific refusal_reason codes including 'data_truncated' and 'tool_error'. Annotations already mark read-only and idempotent, and the description adds refusal behavior and cost without contradicting them.

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

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

The description is packed into five dense sentences, each carrying essential information: purpose, process, return format, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with the key differentiator and contains no filler or redundant content.

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

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

Given the tool's complexity and lack of an output schema, the description comprehensively covers the return structure, all possible refusal reasons, and appropriate use cases. It also hints at data truncation handling via the refusal_reason. The combination of routing, extraction, and refusal behavior is fully explained.

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

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

Schema description coverage is 100% with all parameters documented as aliases for the natural-language 'question' field. The description adds no additional parameter-specific meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers ONLY from tool results, distinguishing it from sibling ask_pipeworx. It specifies the process of routing, fetching, and extracting, and lists the return structure and refusal modes, making 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?

Explicit when-to-use guidance is provided: 'whenever an answer will be quoted, cited, or acted on' with examples like financial verdicts and legal claims. It also states when not to use by saying 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost, naming the alternative.

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 safe, read-only, idempotent behavior. Description goes far beyond with detailed explanations of response shapes, resolver contracts, parent event extraction, safety mechanisms, edge cases (closed markets, wide spreads), and resolution-rule risk. No contradiction with annotations.

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

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

Description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). First sentence captures purpose. Could be more concise, but effective organization aids quick scanning.

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

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

Given no output schema, the description thoroughly covers return values, edge cases, and behavioral nuances. All relevant aspects are addressed, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, so baseline 3. Description adds significant value by explaining how parameters work: market can be slug/URL/question, depth controls fan-out, include_raw controls response size and when to use true. Exceeds baseline.

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

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

Clearly states it researches Polymarket bets by pulling Pipeworx data, with examples of inputs and outputs. However, it does not explicitly differentiate from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage', leaving potential ambiguity.

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

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

Provides explicit use cases ('should I bet on X', etc.) and classifiers, but lacks exclusions or when not to use the tool. No direct alternatives mentioned, 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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context: the source (NASA/JPL CNEOS) and that it is 'keyless' (no API key required). No contradictions with annotations.

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

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

The description is a single sentence that is well-structured and front-loaded with source and purpose. Every part (source, action, scope, output fields, keyless) is essential and concisely stated.

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

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

Given the lack of an output schema, the description adequately hints at the output structure by listing three key fields (miss distance, relative velocity, absolute magnitude). Combined with rich annotations and clear parameters, the description is complete for a list tool.

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

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

Schema coverage is 100% with detailed descriptions for all four parameters (start, end, limit, max_distance). The description does not add new meaning beyond summarizing output fields, so it meets the baseline of 3 without needing to compensate.

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

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

The description clearly states the action ('list'), the resource ('near-Earth close approaches'), the scope ('to Earth in a date range'), and the output fields (miss distance, relative velocity, absolute magnitude). It distinguishes from sibling tools like impact_risk or get_small_body by focusing specifically on listing approaches with orbital parameters.

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 listing close approaches in a date range but does not explicitly state when to use this tool versus alternatives like impact_risk or recent_fireballs. No when-not-to-use or exclusion criteria are provided, leaving the agent to infer context from the tool name.

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

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

Describes data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), sorting behavior, and output format (paired data + URIs), adding 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?

Concise and front-loaded with examples, but dense. Could benefit from slight structuring (e.g., bullet points).

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?

All parameters explained, return format described, and use case clarified. Complete for a 2-parameter tool with no output schema.

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

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

Schema coverage is 100% and the description adds detailed semantics: for type it explains what each enum value does, for values it specifies expected inputs (tickers/CIKs vs drug names).

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, lists example queries, and distinguishes from sequential lookups (e.g., 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong usage guidance and 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?

Rich behavioral context beyond annotations: account/paid-tier requirements, parallel routing to 5,529 tools, findings packet structure with verbatim evidence + confidence + source + fetched_at + gaps[] never invented, contradictions[] for standard/thorough, hop field, citation_uri only when fetchable, semantic excerpting, and 15-90s timing. No contradiction with annotations.

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

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

The description is long and dense, but every sentence carries important information. It is front-loaded with the critical account requirement and sign-in fallback. Somewhat rambling structure, but efficient for the tool's complexity.

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

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

Despite no output schema, the description fully explains the return packet (findings, gaps[], contradictions[], hop, citation_uri), time expectations, and error/edge-case behavior (empty gaps for non-catalog topics). Covers prerequisites, alternatives, and depth variations. Complete for a complex research 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 already covers both parameters at 100%, but the description adds meaningful semantics: depth modes are explained in detail ('quick=3 (single hop)', 'standard=5... adds a gap-recovery hop', 'thorough=8... adds a full iterative hop') and question is described as supporting 'Broad/multi-part' queries. This goes beyond the schema's terse 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 a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It distinguishes from siblings by noting this is NOT open-web search and contrasting with ask_pipeworx for single lookups. The decomposition and parallel routing behavior is explicitly described.

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: 'Best for broad/multi-part questions over structured data'. Explicit alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account prerequisites: 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly. 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 well-structured and front-loaded with purpose, though slightly verbose with domain list. Every sentence is informative, but could be tightened.

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

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

Comprehensive for a discovery tool: explains output (top-N tools with schemas and examples) despite no output schema. Covers main use case adequately.

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

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

Schema description coverage is 100%; description provides natural language examples and mentions aliases but adds little beyond what schema already specifies about the query parameter.

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

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

Clear verb+resource ('Find tools by describing the data or task') with extensive domain examples and differentiation from sibling tools by focusing on discovery rather than specific data retrieval.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Clearly indicates when to use and implies alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by detailing the multi-source fan-out, specific return fields (cik, filings with URIs, fundamentals, patents with sunset note, news, LEI), and the patents soft-fail behavior.

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

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

Description is dense but well-organized, starting with example queries, then usage hierarchy, then details. Slightly lengthy but each sentence adds value; could be tightened 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?

Despite no output schema, description fully explains return fields and behaviors (including soft-fail for patents). Covers input constraints, multiple sources, and edge cases (CIK zero-padding). Comprehensive enough for an agent to use correctly.

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

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

Schema coverage is 100%, and description adds meaning beyond schema: explains `type` is limited to company, `value` expects ticker or zero-padded CIK with examples, and reinforces the constraint that names are not supported.

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 provides a full cross-source profile of US public companies, with example queries and explicit resources (SEC EDGAR, XBRL, USPTO, news, GLEIF). Distinguishes from sibling tool `resolve_entity` for name resolution.

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

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

Explicitly instructs to prefer this tool over chaining single-pack lookups for holistic views. States that names are not supported and recommends using `resolve_entity` first, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. The description adds context about pairing with siblings but no new behavioral traits 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 efficient sentences: the first states the action, the second gives usage context. Front-loaded and no unnecessary words.

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

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

For a simple tool with one parameter and no output schema, the description covers the primary use case and annotation info. Slight gap on return behavior but annotations provide destructiveness.

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 does not add meaning beyond the schema's description of 'key'. The baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by pairing with 'remember' and 'recall', indicating these are complementary operations.

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

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

Provides explicit guidance on when to use: when context is stale, task is done, or to clear sensitive data. Lacks explicit when-not conditions but gives clear 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=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format, which expands understanding beyond annotations. 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 two sentences plus a bullet list of use cases, all front-loaded. Every sentence adds value: first defines the tool, second explains the process and output, third lists practical uses. No unnecessary words.

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

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

The description explains the process (fetch, extract, emit), output format (single text blob), and use cases. With two parameters, no output schema, and annotations covering safety, it provides sufficient context for an agent to use the tool correctly. Could mention URL accessibility or error handling, but not critical for this simple tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific details beyond what the schema provides (e.g., 'max_links' controls entry count is implied). No additional parameter explanation is given, but the high schema coverage means the description doesn't need to compensate.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifies the verb (generate) and resource (URL), and lists specific AI crawlers (ChatGPT, Claude, Perplexity) and use cases. It distinguishes from sibling tools by focusing on llms.txt generation, which is unique 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 provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not mention alternatives or when not to use, but the context is clear and no sibling tool overlaps directly.

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

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

Annotations already declare readOnlyHint and destructiveHint; the description adds the behavioral note 'Keyless' (no API key required) and specifies the output fields. It does not mention rate limits, but the safety profile is well-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?

The description is a single sentence plus a one-word note ('Keyless'), front-loaded with the source and purpose, with no extraneous information.

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

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

The description covers the tool's source, input, and output fields adequately for a simple lookup with one parameter and no output schema, though error handling is omitted.

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

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

With 100% schema coverage, the description's parameter guidance (examples like 'Ceres', '433 Eros') is already in the schema, adding no new meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool looks up asteroids or comets by name/designation and lists specific parameters returned (eccentricity, semi-major axis, etc.), distinguishing it from siblings like 'close_approaches' or 'impact_risk'.

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 the tool is for fetching small body data but does not explicitly say when to use it versus alternatives like 'close_approaches' or 'impact_risk', nor does it provide when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, covering safety. Description adds that it is keyless and sources from NASA/JPL, which is valuable beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with source and purpose. Every word earns its place; 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?

With no output schema and 3 optional parameters, description explains both modes and what is returned per mode. Could mention return format briefly, but complete enough for an AI agent.

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

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

Schema has 100% coverage with descriptions for all 3 parameters. Description adds meaning by specifying that for a single object it returns cumulative impact probability, Palermo/Torino scale, diameter, and impact window, and clarifies list mode limitations for limit and min_probability.

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

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

Description clearly states it provides Earth impact risk for asteroids from NASA/JPL CNEOS Sentry. It distinguishes between querying a single object by designation and listing all tracked objects, which differentiates it from siblings like close_approaches.

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

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

Description explicitly tells the agent to pass a designation for a single object or omit it for a list, providing clear usage context. It does not explicitly mention when to avoid using this tool, but the clarity of modes is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint as true/false appropriately. Description adds context that it returns only active subscriptions by default, and the include_inactive parameter brings in cancelled ones. No contradictions.

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

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

Three concise sentences that efficiently convey purpose, return fields, and usage guidance. No unnecessary information; front-loaded with the key action.

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

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

For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose, usage, return fields, and parameter effect. Sufficient for correct tool selection and invocation.

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

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

Schema description coverage is 100% for the single parameter (include_inactive). Description adds slight extra context by explaining 'include cancelled subscriptions' but does not significantly extend beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings like subscribe and unsubscribe by mentioning its use for review before adding or canceling.

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 to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't explicitly say when not to use, the context with sibling tools (subscribe/unsubscribe) provides clear 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 annotations are all false or unhelpful (readOnlyHint=false, etc.), so the description carries full responsibility. It discloses rate limiting (5 per identifier per day), the fact it's free and excludes from tool-call quota, the claim_token return behavior, and daily human review cadence. There is 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 relatively long but every sentence earns its place, covering scope, exceptions, usage mechanics, and operational details. It is front-loaded with the core purpose, followed by actionable guidance. Slight verbosity prevents a perfect score, but there is 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?

Given a tool with no output schema, the description fully covers what an agent needs: when to use, how to structure feedback, the claim_token round-trip for checking resolution, rate limits, and cost. The only minor vagueness is what counts as an 'identifier' in rate limiting, but this does not impede invocation.

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

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

With 100% schema_description_coverage, the baseline is 3. The description adds meaningful workflow context beyond the schema: it explains how claim_token is obtained and later used, and advises users to describe issues in terms of Pipeworx tools/packs, which informs the 'context' and 'message' parameters. This elevates the score above baseline.

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

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

The description immediately states the tool's purpose with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by focusing on feedback for Pipeworx tools specifically, not performing research or queries. The explicit list of feedback types (bug, feature, data_gap, praise) removes ambiguity.

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 scenarios (bug, feature/data_gap, praise) and a crisp when-not-to-use rule for tools from other MCP servers. It also gives practical guidance on how to formulate feedback (mention Pipeworx tool/pack names, avoid pasting end-user prompts), and describes the claim_token workflow for following up.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). This supplements 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 compact (3 sentences plus bulleted use cases), front-loaded with the primary purpose, and every sentence adds value. No redundancy or fluff.

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

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

Given the simple tool (1 optional param, no output schema), the description covers purpose, use cases, data source, caching, and privacy. Nothing essential is missing.

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

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

Schema coverage is 100% with clear enum and description. The description adds extra semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which aids parameter selection beyond schema definitions.

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 'Returns' and the resource: 'the top tools, top packs, and total call volume over a recent window.' It distinguishes from sibling tools by focusing on trending usage derived from other AI agents' calls.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and alignment checking. However, no exclusions or alternative sibling tools are mentioned, so it falls short of a 5.

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

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

Annotations indicate a safe, read-only, idempotent tool. The description goes beyond by detailing behavior in each mode, the fill check, semantic anchor for cross-event pairs, and partition filter, providing rich behavioral context.

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

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

The description is lengthy but well-structured, starting with overall purpose, then detailing each mode. While it contains technical details that might be dense, every sentence adds value. Minor redundancy in explaining partition_check.

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

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

Given no output schema, the description thoroughly explains the response structure (opportunities[] with fields, partition_check), covers edge cases like placeholder filtering and fill risk, and is contextually complete for an arbitrage detection tool.

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

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

Schema coverage is 100%, but the description adds significant context: explains what 'event' and 'topic' do, how they affect scanning, and provides examples. This goes well beyond the schema descriptions.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, clearly distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides detailed guidance on when to use each mode (event vs topic), explains cross-event mode catches patterns single-event misses, and advises against trading when fill check indicates negative realizable edge. It also references polymarket_fill_risk for custom sizing.

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

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

The description provides extensive behavioral details far beyond the annotations (readOnlyHint, etc.). It explains the three model families, response structure (by_segment, fed_candidates, diagnostics), caching behavior (1h at KV level), and edge cases like placeholder-slug filtering and Fed data limitations. This fully discloses how the tool behaves and what to expect.

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, using headers for model families and response sections. It is front-loaded with the core purpose and use case. While not extremely concise, every sentence adds value for the complexity of the tool. A slightly more structured format (e.g., bullet points for segments) could improve quick scanning, but overall it is effective.

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

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

Given the tool has 9 parameters, no output schema, and high complexity (three segments, diagnostics, caching), the description is remarkably complete. It explains the output structure in detail (by_segment, fed_candidates, _diagnostics) and covers interpretation of each field (e.g., edge_pp_net, kelly_fraction, 24h-move warning). The Fed data limitation note adds important 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?

With 100% schema description coverage, the schema already documents all 9 parameters. The description adds significant value by explaining the purpose of tradeable-edge filters, the interaction between min_kelly and min_partition_leg_kelly for partitions, and providing context on defaults and usage (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model').

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case: 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge discovery rather than arbitrage execution, and avoids the need to page through hundreds of markets.

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 identifies the tool as being 'Built for what should I bet on today', implying it is for opportunity discovery. It explains when to use tradeable-edge filters (min_liquidity, max_spread_pp) and notes that Fed candidates are excluded from ranking. However, it does not explicitly state when to use an alternative sibling like polymarket_arbitrage, though the context implies a distinction.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds limitations (60-day TTL, start date), data sources (daily closes, not intraday), and handling of gaps, enhancing transparency beyond annotations.

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

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

Description is detailed but dense, with extensive response field descriptions that could be shortened. Structure is logical with sections, but length detracts from quick consumption.

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, description thoroughly explains response fields (tracked, expired, snapshot_dates) and limitations, making it complete for an agent to understand tool behavior.

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 both parameters fully (100% coverage). Description reaffirms defaults and ranges but adds little new meaning beyond what schema provides.

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

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

Clearly states it tracks edge persistence and decay telemetry, contrasting fresh vs old edges, and distinguishes from sibling polymarket tools by focusing on edge history rather than current edges or arbitrage.

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

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

Provides context on when to use (when edge age matters) and interpretive guidance, but does not explicitly mention alternatives like polymarket_edges or when not to use this tool.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: requires one of 'market' or 'event', walks the order-book ladder, warns about thin books and forced directional risk, and explains output fields. No contradiction.

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

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

The description is front-loaded with critical usage constraints and mode distinctions. While somewhat long (8+ lines), every sentence conveys essential information. Minor redundancy (e.g., repeating default values) could be trimmed.

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

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

No output schema exists, so the description carries full burden of explaining return values. It lists all returned fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk. Covers edge cases (thin books, partial fills) 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%, so baseline is 3. The description adds value by explaining the default for 'side' in basket mode (auto based on partition sum), clarifying 'size_usd' semantics differs for single (max spend/target proceeds) vs basket (shares per leg), and stating clamps (10-1,000,000).

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

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

Clearly identifies the tool as a realizable-vs-theoretical edge check against live order-book depth, with distinct single-market and basket modes. Each mode's input requirements and output values are explicitly listed, making the purpose unmistakable.

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

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

Explicitly directs when to use: before acting on polymarket_arbitrage signals or trades above ~$500. Provides a strong rationale about uncapturable theoretical overround and directional risk from partial fills, distinguishing it from 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 fully aligns with annotations (read-only, open world, idempotent, non-destructive). It goes beyond annotations by detailing the safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining what they mean, providing rich behavioral context that matches the read-only nature.

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

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

The description is lengthy but well-structured: core purpose first, then modes, response details, safety fields. Every sentence is informative, though some details (e.g., the list of topics and specific counters) could potentially be summarized more briefly without loss of clarity. Still, it is efficient given the complexity.

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

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

Given the tool has three optional parameters and no output schema, the description compensates by extensively documenting the response structure (leg prices, spread, safety fields, temporal alignment, counters). It fully prepares the agent for all possible outcomes, including edge cases like mismatched bet shapes or unrelated events.

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 all three parameters. The description adds significant value by explaining the topic list, the override behavior of explicit tickers, providing examples, and clarifying that topic is optional. It exceeds the structured schema by giving usage context.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket, distinguishes from sibling tools like polymarket_arbitrage by focusing on inter-venue discrepancies, and outlines two distinct invocation modes (topic shortcuts and explicit tickers).

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

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

The description provides explicit guidance on usage: it explains that pre-mapped topics may not produce tradeable spreads due to compatibility warnings, and it advises checking fields like compatibility_warning and temporal_alignment. It implicitly tells when not to use (when bet shapes are non-equivalent or temporal alignment is false). However, it does not explicitly list alternative tools for intra-venue analysis, which is a minor gap.

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. Description adds scoping (anonymous IP, key hash, account ID) but doesn't detail error handling or rate limits. Adequate beyond annotations.

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

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

Three sentences, front-loaded with main function, each sentence adds value. No unnecessary words.

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

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

Covers purpose, parameter, scoping, and pairing. No output schema, so return format is inferred. Could mention behavior for missing keys, but otherwise complete for a simple 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 description repeats the schema's description of the key parameter. Provides context about keys from remember but no new parameter semantics 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 retrieves a value saved via remember or lists all keys when omitted, using specific verbs and resource. It distinguishes from sibling tools remember and forget by explicitly mentioning them.

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

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

Provides explicit use cases (look up stored context like ticker, address, notes) and pairs with remember/forget. 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?

Beyond annotations (readOnly, idempotent, non-destructive), description discloses that setting mark_read:true will flag events as read to affect subsequent calls. This adds behavioral context not captured in annotations, enhancing 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?

Four sentences, front-loaded with the main action. Each sentence adds distinct value: what it does, what it returns, filter options, mark_read effect, and alternative access. No unnecessary words.

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

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

Despite no output schema, description specifies return fields (source, citation_uri, raw payload) and flags mark_read behavior. Covers filtering, limits, and alternative access, making it complete for a read-only tool with five optional parameters.

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

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

Schema coverage is 100%, so parameters are well-documented. Description adds examples (e.g., 'sec_8k', 'ISO timestamp') and reinforces the mark_read behavior, meeting the baseline for high coverage but not exceeding 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?

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It details what is returned (source, citation_uri, payload) and distinguishes from siblings like list_subscriptions by focusing on reading alerts rather than managing 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?

Provides practical guidance: mentions filtering by type and since, suggests polling works, and notes an alternative HTTP endpoint for scripts/dashboards. While it doesn't explicitly exclude scenarios, the context is sufficient for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds behavioral context: GDELT→GNews fallback logic, USPTO soft-fail until May 2025, and return format (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

Description is front-loaded with example queries and clear structure. While slightly verbose, every sentence adds value. No redundant content.

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

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

Without an output schema, the description fully explains return format (changes[], total_changes, pipeworx:// URIs). All parameters are documented with usage context, fallback behaviors are described, and alternative tool is mentioned. Complete for agent decision-making.

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 meaning beyond schema: explains type enum constraint, gives date format examples and shorthand meanings, specifies value can be ticker or CIK. Provides usage guidance for each parameter, e.g., recommended since 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?

Description clearly states the tool provides a change feed for companies over a time window, specifying sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool entity_profile by contrasting purpose: 'Use entity_profile instead when you want the static 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 tells when to use this tool vs entity_profile, provides example queries ('What's new with X', 'latest on Y'), and explains input formats (ticker or CIK, date or relative shorthand). Also recommends typical monitoring window ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds transparency by noting 'Keyless' (no authentication) and 'most recent' implying dynamic data. 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?

Single sentence that is front-loaded with the source and key details. Every word serves a purpose 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?

Lists output fields but does not specify output format (e.g., list of objects) or ordering. Given no output schema and moderate complexity, the description adequately covers what the tool provides.

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 does not add additional meaning beyond the schema; it mentions energy in kilotons of TNT which is already in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool returns recent atmospheric fireballs/bolides from NASA/JPL CNEOS, listing specific data fields like date, energy, location, altitude, velocity. It distinguishes itself from sibling tools like close_approaches or impact_risk by focusing on confirmed fireball events.

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 retrieving recent fireball data but does not provide explicit guidance on when to use this tool versus alternatives like close_approaches or impact_risk. No exclusion criteria or scenarios are mentioned.

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

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

Discloses scoping ('scoped by your identifier') and persistence differences ('authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), adding value beyond idempotentHint=true and destructiveHint=false 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 well-structured sentences: purpose, usage, behavioral details. No redundancy, every sentence adds value.

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

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

Given no output schema, the description covers purpose, usage, parameters, and behavioral traits sufficiently. No missing critical information for a simple key-value storage 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, so baseline 3. Description adds concrete examples for key ('subject_property, target_ticker') and value ('findings, addresses, preferences'), providing additional context beyond the schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with a specific verb+resource. It distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning them as pairing operations.

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

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

Provides explicit when-to-use guidance with concrete examples ('resolved ticker, target address, user preference'). Mentions pairing with recall and forget, clarifying alternatives.

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

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

The description discloses rich behavioral details beyond annotations: identifiers are labeled with their source, unresolved identifiers are explicitly listed, enrichment degrades gracefully, and internal cascading lookups occur. This goes well beyond the readOnly/idempotent hints and adds actionable context.

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

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

The description is long but well-structured with examples and supported types. It front-loads the purpose and provides necessary details, though some redundancy exists (e.g., 'replaces 2-3 manual lookups' is repeated at the end). Still, it earns its length given the tool's complexity.

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

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

The tool is complex (two entity types, multiple sources, fallback behavior), and there is no output schema. The description thoroughly explains what is returned, including unresolved identifiers and graceful degradation, making it complete for an agent to understand outcomes.

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

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

Schema already covers parameters, but description enriches them: for company, it specifies '10-digit CIK', accepted input forms (ticker, CIK, company name), and explains return fields (CIK, ticker, company_name, LEI, FIGI). For drug, it details RxCUI, ingredient, brand, and citation format. This adds meaningful semantics 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: resolving user-spoken names to canonical/official identifiers. It provides specific query examples and names the supported entity types (company, drug), distinguishing it from sibling tools like entity_profile and compare_entities.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also clarifies accepted input formats for each type and notes that it replaces 2-3 manual lookups, providing clear context for when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds detail: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. Treats first entity as 'subject' for narrative.

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

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

Three sentences front-loading purpose, then behavior, then use case, then output description. Every sentence adds value. No redundant or vague language.

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 4 parameters, no output schema, the description covers the tool's function, process, and output structure (score, confidence, signal density). It lacks explicit mention of return format details but is sufficient for an agent.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by explaining the 'entities' parameter: first entry is the subject for narrative, rest are competitors. No further detail needed for other parameters.

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, probes with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It distinguishes from sibling 'ai_visibility_check' by emphasizing multi-entity comparison.

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

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

The description provides a clear usage scenario: 'useful for competitive AI-marketing audits' and implies when to use vs. single-entity alternative. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds important behavioral details: partial failure handling (sources_failed list), bundlephobia timing (5-30s on first measurement), and graceful degradation. 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 fairly dense but well-organized, with clear sections and key details. A slight reduction in length could improve conciseness, but no redundant wording is present.

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

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

Despite lacking an output schema, the description fully explains the return structure (summary block, per-advisory detail, links, alternative versions) and failure behavior. For a complex tool with two parameters, this is highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor context (scoped packages accepted, version defaults to latest), but does not significantly enhance understanding beyond what the schema already provides.

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

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

The description clearly states it is a composite check for evaluating an npm package before adding it to a project, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying the npm ecosystem and mentioning fallback to deps.dev:version for other ecosystems.

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

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

Explicitly provides usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies ecosystem scope and fallback behavior for non-npm packages.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds technical details (BGE-base-en, cosine, 500-char windows, 200K char cap with truncation) and notes that passages include offsets for verification.

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

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

Four sentences, all essential. Purpose stated first, then usage guidance, then technical details. 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?

For a 3-param tool with no output schema, the description explains the return format (top-N passages, offsets, similarity scores) and covers edge cases (truncation). 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?

100% schema coverage means parameters already documented well. Description adds real-world usage examples for 'text' and 'query', and mentions the truncation behavior for 'text'.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific examples (SEC filing, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. Does not explicitly list when not to use, but context is clear.

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

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

The description adds rich behavioral context beyond annotations: requires OAuth, returns subscription id, phone verification, rate limits (10/day SMS), webhook HMAC signing, auto-disable after 10 failures. No contradiction with annotations (readOnlyHint=false, etc.).

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

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

The description is well-structured, front-loaded with purpose, then prerequisites, types, and delivery channels. Every sentence adds value, though it is somewhat long but justified for the complexity.

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

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

No output schema exists, but the description covers return value (subscription id), setup requirements, all supported types with examples, and delivery options with technical details. Highly complete for a subscription creation 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 provides detailed examples for each type with optional fields and constraints (e.g., 'pho ne must match verified phone', '10/day cap'). This adds significant meaning beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides explicit context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and mentions delivery channels. It does not explicitly state when not to use or name alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it returns category-bucketed examples with exact tool+argument shapes from a live catalog, and that no-arg call gives full spread. 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?

Front-loaded with key phrases and synonyms. Lists categories and usage instructions efficiently. Slightly long but every sentence adds value.

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

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

Given no output schema, description fully explains return structure (category-bucketed example questions). Covers when to use, parameter behavior, and expected output. Annotations provide safety context. Complete for this simple 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 has 100% coverage with one parameter (topic) described. Description adds concrete use cases, lists possible values (finance, pharma, etc.), and explains effect when omitted, exceeding schema detail.

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

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

Description explicitly states it returns category-bucketed example questions for onboarding, with clear verb ('returns') and resource ('example questions'). Distinguished from siblings by being the entry point, unlike ask_pipeworx or other specific 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?

Directly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains how to use optional topic parameter for focus.

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 ownership enforcement, deactivation vs deletion, and impact on historical events, adding meaningful context beyond annotations which already indicate mutation, idempotency, and non-destructiveness.

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-load the primary action, followed by necessary behavioral details. No unnecessary words.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description fully covers purpose, constraints, and side effects.

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 on the single parameter 'id' with description. The tool description adds minimal extra meaning ('by id') but is sufficient given high schema coverage.

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

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

The description explicitly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Clearly states when to use ('you can only cancel your own subscriptions') and provides behavior detail ('row is deactivated not deleted'), helping the agent decide appropriately.

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

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

Annotations already state read-only, open-world, and idempotent. The description adds crucial behavioral details: the exact verdict set, the use of verbatim evidence with pipeworx:// citations, and the crucial distinction between 'could_not_verify' (verification did not happen due to error) and 'unsupported' (no source exists). This goes far beyond annotations and prevents serious misinterpretation.

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

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

The description is comprehensive yet tightly packed. It front-loads with trigger phrases and a clear statement of purpose, then methodically covers use cases, fallback behavior, return values, and critical caveats. Every sentence adds meaningful information without redundancy, making it longer but efficient for a complex tool.

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

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

This tool has no output schema, so the description must explain what the caller receives. It enumerates all possible verdicts, mentions the included pipeworx:// citation, describes reasoning, and explicitly warns about the semantics of 'could_not_verify' and 'unsupported'. Given the tool's complexity and lack of an output schema, this description is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how tolerance_pct overrides the implied wording, its intended range, and specific use case (hallucination detection). It also clarifies the default behavior ('capped at 5'), which is not fully captured in the schema. The claim parameter is exemplified but the description doesn't need to add more.

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

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

The description opens with explicit natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…'), immediately establishing the tool's purpose as claim verification. It clearly distinguishes itself from other tools by specifying the two execution paths (SEC EDGAR for financial claims, grounded pipeline for everything else) and describing the output (verdict + actual value + citation). This is a specific verb+resource with strong sibling differentiation.

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

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

It provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company-financial vs. other claims and notes that it replaces 4–6 sequential calls, giving a clear sense of when this tool is the right choice over a multi-step alternative.

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