Celestrak

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable context: default model, Anthropic integration with BYO key billing, return format details. 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 efficient sentences with no wasted words. Front-loaded with action and scope, then details model options, return format, and use cases.

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 adequately covers return structure (per-model fields plus combined view). All parameter behaviors explained. Use cases provided. No significant gaps.

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

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

Schema coverage is 100% but description adds significant value: explains default model (Workers AI Llama-3.3-70b free), clarifies when _apiKey is needed and billing implications, provides concrete examples for each 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?

Description clearly states the tool probes LLMs for brand visibility and returns a score (0-100). Distinguishes from sibling tools by focusing on visibility auditing rather than Q&A or research. Specific verb 'probe' and resource 'LLMs' with examples.

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?

Lists explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly contrast with siblings or state when not to use, but 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 cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: it routes to internal tools, fills arguments, returns structured data with stable pipeworx:// URIs, and is a single fast call. No contradictions with annotations; slight additional detail earns a 4.

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: it opens with a decisive 'prefer over web search' directive, lists supported domains, gives examples, then explains escalation paths. Some redundancy exists in the domain list, but each section contributes to tool selection and invocation decisions.

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 broad routing tool with no output schema, the description is remarkably complete: it states the expected return format (structured answer with citations), when to use it, when to escalate, and provides concrete examples. The agent can confidently select and invoke this tool based on the description alone.

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

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

Schema coverage is 100%—all six params are documented aliases for 'question'. The baseline is 3 because the schema already explains the parameter. The description adds value with question-type examples and trigger phrases, helping the agent construct appropriate input beyond the schema's generic 'natural language' note.

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

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

The description clearly states the tool's action: it routes questions to one of 5,529 tools across 1,455 verified sources and returns a structured answer with citation URIs. It also distinguishes itself from direct siblings like ask_pipeworx_grounded and deep_research, making its unique role 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?

It provides explicit 'use whenever' triggers ('what is', 'look up', 'find', factual questions), declares itself the 'default entry point', and names specific alternatives with conditions: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. Even handles the 'breaking news' edge case.

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 that this is a beta version with live candidate routing improvements, that no candidate is currently active (retired on 2026-07-26), and that results are compared against the stable router. It also notes that it is a full working router and does not fall back to anything else. These additions go beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, providing useful experimental-context 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 three sentences and front-loads the key point ('Beta version of ask_pipeworx'). It packs in essential details about the current state, usage, and experimental nature without excessive verbosity. The final sentence about not falling back is slightly redundant but reinforces that it is fully functional, so it earns its place.

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

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

For a complex beta router with no output schema, the description provides a complete picture: purpose, current state, usage equivalence to ask_pipeworx, and experimental edge. It relies on the reader knowing ask_pipeworx's behavior (response shape), but that is acceptable given the sibling context. The coverage is strong overall, though it could have been more self-contained by explicitly stating the natural-language question capability.

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 'question' and a description for the required field. The tool description adds no additional parameter semantics beyond stating that arguments are the same as ask_pipeworx. Since the schema already handles parameter meaning thoroughly, a baseline score of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes this from the stable ask_pipeworx by highlighting the experimental routing improvements. The core functionality (natural-language question routing) is implied via the schema and the reference to ask_pipeworx, making it clear but not fully self-contained.

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

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

The description explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it currently matches ask_pipeworx exactly, implying that for stable behavior one should use ask_pipeworx. It doesn't explicitly mention when not to use it or alternatives like ask_pipeworx_grounded, but the guidance is sufficient for a sibling 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that it costs an extra LLM call, returns refusal reasons when data doesn't answer, and only uses content from tool results to prevent hallucination. This is substantial additional behavior context and does not contradict annotations.

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

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

Though longer than a typical description, it is information-dense with no filler: purpose, routing behavior, return shape, refusal reasons, usage guidance, and cost tradeoff are all packed into a single structured paragraph.

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 complex tool with no output schema, the description compensates by specifying the success return fields (answer, evidence, confidence, etc.) and the explicit refusal contract with enum values. It also explains when to choose this tool over ask_pipeworx, making it fully self-contained for an agent to decide and invoke.

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

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

The input schema already describes all parameters at 100% coverage, with question and five aliases, all meaning the same natural-language question. The description adds no further parameter-specific semantics, so baseline 3 is appropriate.

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

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

The description opens with a specific verb phrase 'Hallucination-resistant answer mode' and states it uses same routing as ask_pipeworx but extracts answers only from tool results, clearly distinguishing it from sibling tools. It names the sibling 'ask_pipeworx' and describes the unique return contract (answer, evidence, refusal reasons).

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

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

It gives explicit 'Use whenever' conditions including high-stakes scenarios like financial verdicts, legal claims, medical lookups, and public statements, and explicitly says to 'prefer ask_pipeworx for casual lookups', naming an alternative and a cost tradeoff.

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 details behavioral traits beyond annotations: low-confidence matches short-circuit, closed markets skip fan-out, wide-spread markets get illiquidity notes, cancellation rules are parsed, and news fallback fields are documented. These are not in readOnlyHint/openWorldHint, adding significant value.

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

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

The description is verbose but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). Every sentence adds necessary detail for a complex tool; however, slight trimming could improve conciseness for LLM token efficiency.

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 comprehensively explains return shapes, resolver contract, parent event extraction, news fields, and safety/edge cases. It covers all necessary context for agent 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?

Despite 100% schema coverage, the description adds context for each parameter: market accepts slug/URL/text, depth has quick/thorough with default, include_raw keeps responses under ~20KB and explains when to use true. Examples complement 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 researches a Polymarket bet by pulling Pipeworx data in one call, specifying verb, resource, and action. It distinguishes from sibling tools like polymarket_arbitrage by focusing on research rather than edge detection.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and detailed fan-out examples per category. It also advises checking market_match_confidence before trusting analysis, offering clear guidance on when results are reliable.

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 data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs. Annotations confirm read-only, idempotent, non-destructive; description adds significant 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?

Information-dense single paragraph with query examples upfront. Every sentence adds value, though some structuring (e.g., bullet points) could improve scanability.

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 data sources, key metrics, sorting, and citation format. Without output schema, description adequately sets expectations for a multi-entity comparison tool.

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

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

Schema covers 100% of parameters. Description adds context: explains what each type retrieves (financials vs. trial data), provides example inputs, and mentions metric-driven sorting.

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

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

Description clearly states side-by-side comparison of 2-5 companies or drugs, with example queries. Distinguishes from sibling tools like entity_profile by emphasizing it replaces sequential single-entity lookups.

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

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

Explicitly advises ALWAYS PREFER over sequential lookups and provides type-specific guidance. Lacks mention of when not to use (e.g., >5 entities), but overall 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 discloses many behavioral traits beyond annotations: it requires an account, is not open-web search, returns a findings packet with gaps[], never invents data, performs second-hop iteration for standard and thorough depths, provides always-fetchable citation_uri, returns contradictions[] for standard/thorough, uses semantic excerpting, and specifies latency ranges. This far exceeds what readOnlyHint and idempotentHint convey, providing rich behavioral context without contradicting annotations.

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

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

The description is long but every sentence earns its place. It opens with a critical account requirement, then the core function, then usage guidance, followed by behavioral details. It is logically organized with no filler. Though dense, it is information-dense and appropriately structured for a tool with such complex capabilities.

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 is complete for a complex tool with no output schema. It explains the return packet (verbatim evidence + confidence + source + fetched_at + citation + gaps[]), the iteration behavior per depth, the contradiction detection, the semantic excerpting, and the expected latency. There is no significant missing context that the agent would need to select or invoke the tool correctly.

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

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

Even though the schema covers 100% of parameters, the description adds substantial meaning. It explains the 'depth' parameter in detail: 'quick=3 (single hop), standard=5 (default; adds a gap-recovery hop... plus a contradictions[] scan)', 'thorough=8 (paid; adds a full iterative hop...'). It also clarifies that 'question' can be broad/multi-part. This goes beyond the schema's simple enum descriptions and enriches the agent's understanding of how parameters affect behavior.

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

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

The description clearly specifies the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with a specific verb ('research') and resource ('structured data sources'). It also distinguishes from siblings by explicitly contrasting with ask_pipeworx and by stating 'this is NOT open-web search.' This is a specific, well-differentiated purpose statement.

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?

Usage guidance is explicit and comprehensive. The description states: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also warns about account requirements and when to fall back to ask_pipeworx. This is clear when-to-use and when-not-to-use guidance with named 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, idempotentHint, and destructiveHint. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed,' providing useful behavioral insight beyond annotations.

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

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

The description is appropriately sized, front-loading the purpose and usage context. Each sentence adds value, though it could be slightly more concise by removing the long list of examples.

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

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

Given no output schema, the description explains the return value (top-N tools with names, descriptions, full schemas). It also covers the limit parameter and usage context, making it fairly complete for a tool discovery function.

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 parameters. The description adds clarity about aliases (task, q, description, search) and the nature of the query, but this is marginal 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: 'Find tools by describing the data or task.' It lists specific domains and explains that it returns the most relevant tools with schemas. This distinguishes it from sibling tools like search_by_name, which focus on data rather than tool discovery.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use the tool, though it does not explicitly mention when not to use it.

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

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

Beyond annotations (readOnlyHint, idempotentHint etc.), the description details the fan-out across multiple sources, specific returned fields (cik, recent_filings, fundamentals with sorted period_end), soft-fail on patents, and fallback behavior for news. 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 thorough and well-organized with example queries first, then purpose, then output details. It could be slightly more concise by grouping some details, but it remains effective and front-loaded.

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

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

Given the tool's complexity (multi-source profile with fallbacks, limitations, and specific return values), the description covers all key points: data sources, exact return fields, sorting, sunset notice, and input constraints. No output schema needed as description covers returns 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%, but the description adds significant meaning: it clarifies that 'value' can be ticker or zero-padded CIK, explicitly states that names are not supported, and explains the format for CIK. This goes well beyond the schema's minimal 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 starts with explicit example queries ('Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company', making the verb, resource, and scope unmistakable. It clearly distinguishes from siblings like 'resolve_entity' by stating when to use that instead.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)'. This is model 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 provide destructiveHint=true and idempotentHint=true. The description adds context about 'sensitive data', which is helpful, but could mention permanence or cascading effects. 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?

Two sentences, front-loaded with the core purpose. Every sentence adds value: purpose, usage context, and related tools.

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 delete tool with clear schema and annotations, the description is complete. It covers purpose, usage guidelines, and relationships to other tools.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description does not add additional parameter details, but the schema is sufficient.

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 'Delete', the resource 'memory', and the method 'by key'. It also distinguishes from sibling tools 'remember' and 'recall' by referencing them.

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

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

The description explicitly lists when to use this tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with 'remember' and 'recall'.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 'Fetches the page, extracts title/description/key links, and emits standard markdown', complementing the annotations with concrete steps. 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 well-structured sentences: first states main action and output format, second lists use cases. Every sentence adds value; 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 the tool's simplicity (2 params, no output schema, clear annotations), the description fully covers purpose, behavior, and usage scenarios. No gaps identified.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description does not add new semantic meaning beyond the schema, but it implicitly explains how 'url' is used (fetched). 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 generates an llms.txt file for a given URL, with specific verb 'Generate' and resource 'llms.txt'. It differentiates from siblings like 'scan_competitor_ai_presence' by focusing on outputting the standard llms.txt format for AI crawlers.

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: getting a client's site indexed, drafting for own project, or auditing competitor's AI visibility. Lacks explicit 'when not to use' or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context that this is catalog/orbital data, not live tracking, and specifies a limit of 100 satellites and the orbital parameters returned. 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, each adding essential info without redundancy. Front-loaded with the core purpose, followed by specifics. Every word earns its place.

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

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

Given the simple structure (1 parameter, no output schema, strong annotations), the description fully covers what the tool does, what it returns (up to 100 satellites, orbital parameters), and what it does not do (live tracking).

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

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

Schema coverage is 100% with a description for the 'group' parameter listing valid values. The description enhances this by providing examples and explaining the concept of groups, adding semantic value beyond the schema.

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

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

The description uses specific verbs ('List orbital elements') and resource ('CelesTrak group'), provides concrete examples (Starlink, GPS, weather), and distinguishes from siblings like get_satellite. It clearly states what the tool does and its scope.

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

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

The description clearly indicates when to use the tool (to get orbital data for entire groups) and implies alternatives (get_satellite for single satellite). However, it does not explicitly state when not to use or list 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 indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the returned orbital parameters and explicitly stating what the tool does not do (live position tracking), which goes beyond the annotations.

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

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

The description is concise, with three sentences that efficiently convey purpose, return details, and scope. No unnecessary information 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?

For a simple retrieval tool with one required parameter and no output schema, the description provides sufficient detail about what data is returned and its limitations (orbital catalog vs. live tracking). It is complete and appropriate for the tool's complexity.

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

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

The input schema has one parameter (norad_id) with 100% description coverage, providing examples and explanation. The description repeats these examples but does not add significant new semantic meaning 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 retrieves satellite orbital elements (TLE/GP data) for a single object by NORAD catalog ID. It specifies the exact parameters returned (e.g., inclination, eccentricity) and distinguishes itself from live position tracking.

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 clarifies that this tool accesses the orbital catalog, not live tracking, which helps an agent decide when to use it. It provides concrete examples (e.g., 25544 = ISS) but does not explicitly list when not to use it or alternative tools for live tracking.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by noting it returns 'active subscriptions' by default and listing specific return fields, but no additional behavioral disclosures needed given safety profile.

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

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

Two sentences, no wasted words, front-loaded purpose, and efficient. 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 the simple tool (one optional param, no output schema), the description covers purpose, return fields, and usage. Could mention pagination or limit, but not required for this scale. Sufficiently complete.

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

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

Schema coverage is 100% with description for the single optional parameter. Description adds no extra meaning beyond what's in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource, and mentions the returned fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by being a read action.

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: to review monitored subscriptions before adding more or to find an id to cancel. This provides clear context for tool selection.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses the claim_token flow for anonymous use, rate limiting (5 per identifier per day), that it is free and does not count against tool-call quota, and that feedback is read daily and affects the roadmap. This goes well beyond structured annotations.

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

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

The description is long but front-loaded with purpose and every sentence serves a function (usage, exclusions, tips, token flow, limits). It could be tightened slightly, but the structure is logical and no sentence is wasted.

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 four optional parameters, the description fully covers what a caller needs: when to use, how to format feedback, what happens with an anonymous filing, how to check resolution, and constraints. There is no ambiguity about the tool's behavior or expected 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 coverage is 100%, so baseline is 3. The description adds value by explaining how type values map to use cases, how claim_token works as a follow-up mechanism, and that context is optional structured info. This goes beyond the schema's field-level 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 opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool as a feedback channel for Pipeworx tools, which distinguishes it from all sibling tools.

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

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

The description explicitly states when to use this tool (bug, feature/data_gap, praise) and provides an exclusion: do not use for other MCP servers' tools, file with that server instead. It also gives a clarifying test for unsure cases (Pipeworx tool names are the ones this connection lists).

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 valuable context: self-aggregating, derived from CF analytics-engine, no PII, caching details (5min-1h). No contradictions.

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

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

Four sentences, each earning its place: first states purpose, second lists use cases, third explains data source and privacy, fourth notes caching. 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 only one parameter and no output schema, description fully explains what the tool returns, how it works, and caching behavior. No missing information for an agent to decide on usage.

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

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

Schema has 100% coverage with enum and description for 'window'. The description adds practical guidance on window selection ('shorter windows surface what's hot; longer show steady-state demand'), going beyond the schema enum labels.

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

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

Clearly describes the tool as returning top tools, packs, and call volume over a specified window. Specific verb ('returns') and resource ('Pipeworx trending'). Distinguishes from siblings by focusing on current agent usage trends.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). Provides context but does not compare directly with sibling tools or state when not to use.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: scanning top 200 markets, monotonicity checks, partition sum, Jaccard similarity for cross-event, placeholder fraction filter, fill check against CLOB depth. It also explains response fields and conditions for null signals. 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 long but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear separation of modes. It front-loads the core purpose. While dense, every sentence adds value. Could be slightly more concise, but it's well-organized 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?

Despite lacking an output schema, the description details the response structure (opportunities[], partition_check, fill_check fields) and edge cases (null signal for high placeholder fraction, realizable_edge_pp <= 0). It references polymarket_fill_risk for custom sizing. The description is complete for a complex tool with multiple modes and checks.

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 substantial meaning: explains modes, expected values (slug, URL, seed question), and internal logic for each parameter. Provides examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal'. Goes beyond schema by describing how the tool uses each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and explains the resource (Polymarket markets). The verb 'Find' is specific, and it differentiates from siblings 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 explicit guidance on when to use each parameter: no args for trending scan, event for specific market partition check, topic for cross-event scan. It recommends event mode for specific markets and explains what cross-event mode catches. It also includes fill check guidance on when not to trade. However, it does not explicitly compare with sibling tools like polymarket_edges, which would further improve guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description details the three model segments, edge calculation (net of slippage, Kelly fractions), response structure (diagnostics, Fed note), and caching behavior ('Cached 1h at the KV level'). It also mentions limitations like the unreliability of Fed bets without paid 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?

The description is long but efficiently packed with information. It is structured by segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and response fields, making it scannable. Every sentence adds essential detail. Minor verbosity in technical explanations could be trimmed, but it's justified by the tool's complexity.

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

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

Given the tool's complexity (9 parameters, three model families, diagnostics, tradeable-edge knobs), the description completely covers what the tool does, its input knobs, output structure, and behavioral nuances. Without an output schema, it adequately explains the return fields and diagnostics so agents can parse the response.

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

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

The input schema already describes all 9 parameters (100% coverage). The description adds value by explaining usage context (e.g., 'min_kelly' skips small opportunities, 'slippage_pp' subtracts from edge, 'min_partition_leg_kelly' applies per-leg for partitions). However, not every parameter gets individual elaboration in the description; some are only covered by 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb 'scan' and the resource 'Polymarket markets' with a distinct outcome (disagreement detection). The mention of 'Built for "what should I bet on today"' distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker, which focus on specific subsets.

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

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

The description provides clear context on when to use (to discover opportunities) and explains the tradeable-edge knobs (min_liquidity, max_spread_pp) that help decide viability. However, it does not explicitly state when not to use this tool or suggest alternative tools for other scenarios, such as if a specific arbitrage is needed.

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. The description adds essential details: data comes from daily snapshots bounded by a 60-day TTL, decay numbers are from daily closes not intraday, and gaps indicate no scan occurred. No contradictions with annotations.

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

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

The description is detailed but well-structured with clear sections (RESPONSE, LIMITS). It is not overly terse but every sentence adds value. Could be slightly more concise, but the structure aids readability.

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

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

Given no output schema, the description compensates by fully detailing the response format (tracked, expired, snapshot_dates) and limitations. It covers all necessary context for an agent to understand what the tool returns and its constraints.

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

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

Input schema fully documents both parameters (days, window) with descriptions and defaults. The description reinforces these with additional context (e.g., max 30 for days) and explains the response structure, which adds value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools by focusing on tracking edges over time, answering specific questions about edge lifespan and trends.

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 when to use the tool (e.g., to understand edge persistence) but does not explicitly state when not to use it or contrast it with alternatives like polymarket_edges or polymarket_arbitrage. It provides context like the difference between fresh and old edges, which guides usage.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds context about walking the ladder, returning fill details and verdicts, and warns about thin books and partial fills, enhancing transparency without contradicting annotations.

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

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

The description is fairly long (~400 words) but well-structured with clear sections for single-market and basket modes. Every sentence adds essential context, though it could be slightly more concise without losing clarity.

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

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

Despite the absence of an output schema, the description comprehensively lists all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It covers behavior, constraints, and risks completely.

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

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

Schema description coverage is 100%, with all four parameters described. The description adds value by explaining default values (size_usd=1000), mode-specific interpretations (size_usd as settlement notional in basket mode), and side auto-detection logic for basket mode, going beyond the schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns against misuse, explaining that partial basket fills convert an arb into an unhedged directional position.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: compatibility_warning conditions (non-equivalent bet shapes, semantic mismatch), temporal_alignment impact, and skipped cross-type/subtype counters. No contradictions.

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

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

The description is well-structured with sections for modes, response, and safety fields. It is slightly verbose but every sentence provides useful information. The final caution about pre-mapped topics is a valuable qualifier.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread array, safety fields). It covers temporal alignment, compatibility warnings, and skipped types, making the tool's behavior fully understandable.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining the topic list and the override mechanism for explicit parameters, going beyond the schema's basic 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 defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue differences rather than intra-venue opportunities.

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

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

The description explains two modes (topic and explicit) with examples and specifies when to use each. It also warns about compatibility warnings and temporal alignment, indicating when the tool's output is not meaningful. However, it does not explicitly differentiate from sibling tools like polymarket_edges.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about scoping to identifier and listing behavior, but does not contradict annotations.

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

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

Three sentences, front-loaded with essential purpose, no unnecessary words, well-structured.

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

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

Given simple tool with one optional param and no output schema, description covers retrieval, listing, scoping, and relationships to sibling tools completely.

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

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

Schema coverage is 100% and the schema already explains that omitting key lists all keys. Description adds no significant new parameter detail beyond what schema provides.

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

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

The description clearly states the verb ('retrieve' or 'list'), the resource ('saved value' or 'keys'), and the condition (omit key to list all). It distinguishes from sibling tools remember and forget.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and mentions scoping to user identifier. Also advises pairing with remember and forget, providing clear when-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=true, destructiveHint=false, etc., but the description adds significant behavioral context: it explains the returned fields (source, citation_uri, raw event payload), the effect of mark_read (flags events read so next call shows newer ones), and states that polling works fine. It also notes the same feed is accessible via HTTP. No contradictions with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the main purpose. Each sentence adds value: first sentence states purpose and return fields, second explains filter options, third explains mark_read, fourth mentions polling and alternative access. No wasted words.

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

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

Despite no output schema, the description lists key return fields (source, citation_uri, raw event payload). It explains mark_read behavior and filter options. Missing explicit mention of limit default (schema says 50) and unread_only behavior, but overall it is fairly complete for a tool with optional parameters. Could be slightly more detailed on response format, but adequate.

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

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

Schema covers all 5 parameters with descriptions (100% coverage), but the description adds value by providing usage examples: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and explains the mark_read behavior. For limit and unread_only, the schema already describes them, so the description's addition is moderate. With full schema coverage, baseline is 3, but the description's examples and context elevate it to 4.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts with specific fields (source, citation_uri, raw payload). It uses a specific verb ('Pull') and identifies the resource ('fired events from your subscription feed'). This clearly distinguishes it from sibling tools like those for subscribing or querying AI, as it focuses on reading alerts from a persisted feed.

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 guidance on when to use the tool, such as 'Polls work fine' and mentions an alternative GET endpoint for scripts and dashboards. However, it does not explicitly state when not to use this tool versus other reading tools (e.g., ask_pipeworx). The alternative mention helps some, but more explicit exclusion of other tools would improve clarity.

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

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

Annotations already mark readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context: it mentions the parallel fan-out, the fallback from GDELT to GNews, and the soft-fail for USPTO. It also describes the return structure with changes grouped by source and citation URIs, which is beyond the annotations.

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

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

The description is a single well-structured paragraph that front-loads example queries and covers all necessary information without unnecessary repetition. It is appropriately sized for the complexity.

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

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

Given there is no output schema, the description explains the return structure (changes grouped by source, total_changes count, citation URIs). It also details the sources, fallback behavior, and parameter options. For a tool with 3 parameters, this is remarkably 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%, baseline 3. The description adds meaning: explains that 'since' accepts ISO date or relative shorthand, recommends '30d' or '1m' for typical monitoring, clarifies that 'type' only supports 'company', and gives examples for 'value' (ticker or CIK). This adds significant value beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, using specific verbs like 'fans out' and listing multiple sources (SEC EDGAR, GDELT, GNews, USPTO). It also explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use the alternative.

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

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

The description gives explicit guidance: 'Use entity_profile instead when you want the static profile' and provides example queries. It clearly defines the scope (changes over time) versus static data.

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

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

Description adds key behavior beyond annotations: scoping by identifier, persistence durations (persistent for authenticated, 24h for anonymous). Annotations already indicate non-readonly, non-destructive, and idempotent, which are consistent.

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: first states purpose, second gives usage context with examples, third provides technical details. No wasted words.

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

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

Given no output schema, description still covers storage behavior, scoping, and pairing with related tools. Sufficient for agent to understand tool's role 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 coverage is 100% so baseline is 3. Description does not add significant semantics beyond the schema beyond giving example values for 'key'.

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 and resource. It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget'.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward'. Gives concrete examples (resolved ticker, target address, etc.) and mentions pairing with recall and forget.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: identifiers are labelled with source, unresolved identifiers are listed under `unresolved`, enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, and each call cascades through multiple endpoints. 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 verbose and poorly structured: it opens with a long list of example queries, then buries the core purpose in the middle, and ends with a massive run-on sentence inside SUPPORTED TYPES. While information-dense, it is not front-loaded and would benefit from tighter organization.

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

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

For a tool with no output schema, the description is remarkably complete: it specifies return value contents (source-labelled identifiers), unresolved identifier handling, graceful degradation when upstream services fail, and internal cascade behavior. It lacks an exact response structure but covers the essential behavioral context.

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

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

Schema coverage is already 100% (type enum with descriptions and value format examples), but the description adds rich meaning: for company it details the identifier spine (CIK/ticker/LEI/FIGI) and the unresolved behavior, for drug it specifies RxCUI/ingredient/brand and the citation format. This goes well beyond the schema's parameter descriptions.

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

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

The description opens with a block of concrete example queries and explicitly states the tool resolves a user-spoken NAME to canonical identifiers. It further distinguishes itself from siblings with 'Use FIRST whenever you have a name but need an ID' and clearly enumerates the two supported entity types.

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 directive for when to use the tool ('Use FIRST whenever you have a name but need an ID') and notes that it replaces 2-3 manual lookups. However, it does not explicitly contrast with sibling tools like search_by_name or entity_profile, nor does it state conditions when the tool should NOT be used.

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 include readOnlyHint, idempotentHint, and destructiveHint=false, all consistent with the description. The description adds details: probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence provides essential information without fluff. It is concise and well-structured.

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

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

Although there is no output schema, the description explains the return format (ranked list with score, confidence, signal density) and the process. It does not give a detailed example output, but it is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: the first entity is treated as the 'subject' for narrative, rest as competitors. It also explains that models like 'anthropic' require an _apiKey, clarifying parameter interdependence.

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, specifying the verb 'compare' and the resource 'AI visibility'. It also implicitly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic 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 concrete use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entities. Still clear enough for an agent to infer appropriate context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: partial failures, timing (5-30s for bundlephobia), and graceful degradation. 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 detailed and front-loaded with core purpose. While slightly verbose, each sentence adds meaningful information. Efficiently structured.

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

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

Despite no output schema, the description thoroughly explains return format (summary block, per-advisory detail, links, alternative versions). Covers edge cases (partial failures, timing). Complete for a composite 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 descriptions. Description adds context about default version behavior and scoped package acceptance. Slight improvement over 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 defines composite check for npm package evaluation, combining multiple sources (deps.dev, bundlephobia). Distinguishes from siblings by specifying NPM-only scope and use case.

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

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

Explicit usage guidance: 'when an agent asks...' and 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' Provides clear context and alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds context that data is catalog/orbital not live tracking, and mentions 50-result limit, adding value beyond annotations.

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

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

Two sentences cover purpose, examples, result limit, and data nature. No unnecessary words or repetition.

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 search tool with one parameter and no output schema, the description adequately explains return values and limitations. Could mention default sort or pagination but not critical.

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

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

Single parameter 'name' fully documented in schema with description and examples. Description adds no additional semantic detail 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 searching satellite catalog by name substring, returning orbital elements. Provides examples and result limit. Does not explicitly differentiate from possibly similar sibling 'get_satellite', but resource and action are specific.

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

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

Implied usage through examples and result description, but no explicit guidance on when to use vs. alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that each passage carries character offsets for verification. 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 three sentences, front-loaded with the core action. Each sentence serves a purpose: stating the function, providing usage context, and detailing technical behavior. No fluff or 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 no output schema, the description covers the return format ('top-N passages with character offsets and similarity scores') and highlights important constraints (200K char cap, truncation flag). Could be slightly improved by explicitly stating whether offsets are start/end positions, but overall 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 parameters are already described. The description adds value by providing natural-language query examples (e.g., 'supply-chain risk') and clarifying the text length limit and default limit. This enhances understanding beyond the schema descriptions.

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

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

Description clearly states 'Semantic search INSIDE a fetched record', specifying the verb (search) and resource (record). It distinguishes from sibling tools like search_by_name by emphasizing the post-fetch context and 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 'Use when the record is too big to cram into the prompt' and explains that it saves context by returning only relevant passages. Also mentions pairing with ask_pipeworx_grounded for a typical workflow, providing clear guidance on when to use this tool vs. alternatives.

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

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

Annotations indicate mutation (readOnlyHint=false) but description adds critical details: returns new subscription ID, SMS cap of 10/day, webhook auto-disable after 10 failures, and signing secret returned once. 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?

Description is dense but well-organized: main purpose first, then supported types with examples, then delivery channels with details. No superfluous sentences.

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

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

Completely covers input semantics for a complex tool with 3 parameters, nested objects, multiple types, and delivery channels. Mentions return value and related tools/endpoints, despite 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 description adds rich examples for type, params, and delivery objects, including constraints like phone verification, SMS cap, and webhook signing.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Verb and resource are explicit, and it distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly mentions requirement of Pipeworx OAuth account, indicating when not to use (anonymous/BYO). Provides context on supported types and delivery channels, but does not explicitly contrast with all siblings.

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

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

Adds rich behavioral detail beyond annotations: describes output structure (category-bucketed questions with exact tool+argument shape) and use cases. No contradiction with annotations (readOnly, idempotent, etc.).

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

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

Well-structured but slightly verbose; front-loaded with trigger phrases. Every sentence adds value, but could be slightly more compact without losing clarity.

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

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

Given no output schema, the description fully explains what is returned (categories, example questions, tool references). Sufficient for an agent to understand and use the tool.

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

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

Schema coverage is 100%, and description adds significant value: explains the optional 'topic' parameter with examples and clarifies default behavior (full spread). No ambiguity.

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 returns category-bucketed example questions with tool+argument shape, and distinguishes from siblings like ask_pipeworx by noting it's the onboarding entry point. Specific verb (suggest questions) and resource (what Pipeworx can do).

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 call with no arguments for full spread or with topic to focus, and advises using it first when unsure of capabilities. Does not explicitly list exclusions but context implies not for direct answers.

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 valuable behavioral context beyond annotations, explaining that rows are deactivated (not deleted) and ownership is enforced. This aligns with annotations (destructiveHint=false, readOnlyHint=false) and clarifies the mutation's side effects.

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

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

Two concise sentences with front-loaded action and constraints. No redundant or wasted words.

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

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

For a simple tool with one parameter, the description covers ownership, behavior (deactivate vs delete), and relation to sibling tool (recent_alerts), making it fully informative.

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 mentions 'subscription id (uuid)' which matches schema; no additional parameter semantics are provided 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 action ('cancel a subscription'), the resource (subscription by id), and distinguishes from siblings like 'subscribe' and 'recent_alerts' by noting it only deactivates and preserves historical 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 specifies ownership enforcement ('only cancel your own subscriptions') and hints at when to use 'recent_alerts' for historical events, but lacks explicit 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?

Even though annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds substantial context: dual pipeline behavior, exact percent-delta math, verdict semantics, and the critical distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source). It also warns callers not to treat a validation failure as evidence, which is valuable beyond the structured fields.

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

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

The description is front-loaded with trigger phrases and purpose, then moves through routing, return values, and important caller warnings. It is moderately long but every sentence adds value: examples, verdict list, error semantics, and a note about replacing multiple calls. There is no filler or 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?

Since there is no output schema, the description must explain return values, and it does: verdicts, actual value with citation, reasoning, and verification_error details. It also covers failure modes, the unsupported case, and the efficiency benefit. For a complex two-path claim verification tool, this is complete.

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

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

The input schema already covers both parameters fully (100% with examples and constraints), so the description does not need to compensate. It does add slight context about percent-delta math and tolerance behavior, but the schema carries the heavy lifting. This matches the baseline for 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 opens with concrete trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states 'natural-language claim verification against authoritative sources.' It clearly identifies the tool's verb (validate/verify) and resource (claims), and distinguishes it from sibling research/compare tools by focusing on fact-checking user statements.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs. other claims. It also notes it 'replaces 4–6 sequential calls,' giving practical guidance. However, it does not explicitly name alternative sibling tools to avoid or state when not to use it, so it falls just 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.