Here

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

Description adds critical behavioral context beyond annotations: it makes external API calls (Anthropic requires BYO key with cost), returns per-model structured data, and is idempotent/read-only. No contradiction with annotations; fully transparent.

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

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

Four sentences front-loaded with core purpose and key details. No redundant information, though return format could be more compact. Still efficient and well-structured.

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

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

Given 4 parameters, rich annotations, and no output schema, description covers purpose, parameter usage, and return structure (per-model fields). Mentions raw_response but could detail combined view. Still adequate for agent to use correctly.

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

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

Schema coverage is 100% but description adds value: explains entity is the thing to ask about, models list with defaults, _apiKey only needed for Anthropic, context for disambiguation. Adds examples and clarifies optionality beyond 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 the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It differentiates from sibling tools like ask_pipeworx by focusing on multiple model probing and scoring rather than single knowledge base queries.

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

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

Explains default model (free Workers AI) and condition for Anthropic (requires API key). States use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already declare the tool as read-only, open-world, and non-destructive. The description adds valuable context: routing to verified sources, filling arguments, returning pipeworx:// citations, and being fast on every tier. This goes beyond simple safety disclosure without contradicting 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 long but information-dense and well-structured: a primary preference directive, a list of covered domains, usage triggers, examples, and escalation paths. It is front-loaded with the most important guidance and each sentence earns its place, though a tighter version could remove some redundancy.

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

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

The description fully covers purpose, usage, alternatives, and behavior. It mentions the response format (structured answer with citations), which is important given the absence of an output schema. Minor gaps remain regarding error handling or no-match scenarios, but overall it is complete enough for a question-answering tool.

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

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

Schema description coverage is 100%, and the question property is clearly documented with aliases (query, q, prompt, text, input). The tool description provides example questions but doesn't add parameter syntax beyond what the schema already includes. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool routes questions to one of 5,529 tools and returns structured answers with citations. It explicitly differentiates from siblings by naming ask_pipeworx_grounded and deep_research as escalation paths. The verb 'routes' and the resource scope (authoritative data) make its purpose unambiguous.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and provides explicit when-to-use guidance covering many trigger phrases and domains. It names alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad queries. This is exemplary guidance for an agent.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses crucial behavioral traits: it's a full working router with no fallback, currently matches ask_pipeworx exactly because no candidate is active, and its results are compared against the stable router. This provides rich context about experimental status and operational behavior.

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

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

The description is four sentences, front-loaded with the essential 'Beta version of ask_pipeworx' and explains identity, current status, usage, and fallback behavior without redundancy. Every sentence adds value; the date and tool count are specific and relevant, not padding.

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

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

Given the tool's complexity (universal router with 5,529 tools) and absence of an output schema, the description fully covers what the agent needs: it states the tool's relationship to ask_pipeworx, the current inactive-candidate state, and that response shape is identical. This is complete context for safe and effective invocation.

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

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

Schema coverage is 100%, with all parameters documented as aliases for 'question'. The description adds no extra meaning beyond the schema—it only references 'same arguments' as ask_pipeworx, which is already clear from the schema. Therefore, the 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 a beta version of ask_pipeworx, a universal router, and specifies it has identical tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by explicitly framing it as the experimental edge with candidate routing improvements.

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 it exactly like ask_pipeworx when you want the newest routing.' This names the alternative (ask_pipeworx) and the condition for use. However, it lacks an explicit when-not or exclusionary statement (e.g., 'use stable for production-critical requests'), so it falls just short of a perfect score.

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, but the description adds substantial behavioral context: it discloses the extra LLM call cost, the exact return structure with evidence and refusal reasons, and the edge cases like data_truncated and no_tool_match. This exceeds what annotations alone provide and does not contradict them.

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

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

Three focused sentences: the first states the core purpose and differentiator, the second details the output and refusal behavior, and the third covers use cases and cost trade-off. Every sentence earns its place, no fluff or redundancy, and the most important information is front-loaded.

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

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

The description is remarkably complete for a tool with no output schema or nested objects. It covers the routing process, return structure (including refusal reasons), use cases, and cost implication. Combined with the annotations and sibling tool context, an agent has all the information needed to decide when to invoke this tool and 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?

The input schema has 100% description coverage with all six parameters (one required, five aliases) fully documented. The description does not add parameter-specific semantics, but the baseline of 3 is appropriate because the schema already carries the full burden. The description's mention of routing and fetching implicitly relies on the question parameter, yet no additional meaning is added.

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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's function and context. It explains the routing and extraction process, explicitly distinguishing itself from ask_pipeworx by emphasizing grounded-only extraction. The verb+resource structure is specific and differentiates this from siblings.

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

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

The description explicitly states 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and contrasts with ask_pipeworx by saying 'prefer ask_pipeworx for casual lookups.' This provides clear when-to-use and when-not-to-use guidance with a named alternative, making it exemplary.

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

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

The description extensively covers behavioral traits beyond annotations: fan-out process, fan-out examples per category, response shapes, safety mechanisms (low-confidence short-circuit, closed markets), resolution rule risk, parent event extraction, and news fallback fields. Annotations provide basic hints, and the description enriches them significantly.

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 paragraphs and bolded key terms. Every sentence adds value; however, it is somewhat verbose and could be tightened. Still, it is appropriately detailed for the tool's complexity.

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

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

Given no output schema, the description fully explains the return fields (result.market, result.analysis, result.evidence), edge cases (low confidence, closed markets, wide spreads), cancellation rules, and parent event extraction. It is complete and leaves no major 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?

The description adds substantial meaning beyond the schema: explains that market accepts slug, URL, or question text; depth parameter options 'quick' vs 'thorough' with explanation; include_raw parameter with context on when to use true/false and size implications. All 3 parameters benefit from detailed elaboration.

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, with a specific verb and resource. It distinguishes from siblings by its single-bet deep research focus versus other tools like polymarket_edges for edge scanning.

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 scenarios are provided ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it doesn't explicitly list alternative tools, the context is clear. Slight deduction for lacking 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?

Description adds behavioral context beyond annotations: mentions data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, result sorting by primary metric, and citation URIs. No contradiction with annotations (readOnly, openWorld, idempotent).

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

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

Single paragraph is dense but every sentence adds value. Front-loaded with trigger phrases. Slightly less structured than ideal (could benefit from bullet points), but still highly efficient.

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

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

Despite no output schema, description explains return format (paired data + URI citations) and result ordering. Covers both entity types, fiscal year handling, and data sources. Complete for the tool's complexity.

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

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

Schema coverage is 100%, and description adds extra meaning: examples for 'values' (tickers/CIKs, drug names), constraints (2-5 items), and explains how type affects data pulled. Adds sorting and data source details beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases like 'which is bigger' and 'head to head'. It distinguishes from siblings by noting it replaces 8-15 sequential 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?

Explicit when-to-use examples provided. States 'ALWAYS PREFER over sequential single-pack lookups' and differentiates behavior for type='company' vs. type='drug'. Provides clear context for alternative tool usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial non-annotation context: account requirements and paid plan for 'thorough', expected latency (15-60s), the guarantee that gaps[] are explicit and never invented, semantic excerpting of large records, and the condition that citation_uri appears only when resolvable. No contradiction with annotations.

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

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

The description is long but every sentence carries substantive guidance. It is front-loaded with the most critical operational constraints (account, fallback) before diving into technical details. Some redundancy exists (e.g., contradictions[] mentioned twice, citation_uri explained twice), but given the tool's complexity, the length is justified without being excessively bloated.

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

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

With no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and a hop field. It also covers prerequisites, latency, edge cases (unresolvable citations), and how large records are handled. The description is comprehensive enough to invoke the tool correctly without additional 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?

The schema provides 100% coverage of both parameters, with detailed descriptions of the depth enum. The description adds meaningful context beyond the schema: 'thorough' requires a paid plan, and it explains how depth levels affect gap recovery and contradiction scanning. It also offers example questions. While the schema already does heavy lifting, the added pricing and latency info raises it above baseline.

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

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

The description clearly states that this is 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly notes 'this is NOT open-web search'. It also distinguishes itself from the sibling ask_pipeworx by stating it is designed for 'broad/multi-part questions', leaving no ambiguity about its purpose.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also clarifies that deep_research is ideal for 'broad/multi-part questions', making the decision 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 provide readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: returns top-N most relevant tools with names, descriptions, full input schemas with curated examples, ready to call directly with no second lookup. 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 moderately long but each sentence adds value: purpose, use cases, output details, and guidance. Could be slightly tightened, but remains clear 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 6 parameters, no output schema, and 32 sibling tools, the description is very complete. It explains what the tool returns (names, descriptions, full schemas with examples), that results are ready to call, and when to use it. 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% with all parameters documented. The description adds context beyond the schema by explaining the query parameter accepts natural language and lists example tasks (e.g., 'analyze housing market trends'). It also clarifies the limit parameter default and max.

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 tools by describing data/task, lists specific domains (SEC filings, financials, etc.), and explains it returns top-N relevant tools with full schemas. This distinguishes it from siblings like 'recall' or 'search_within' which have different purposes.

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 you need to browse, search, look up, or discover what tools exist for' and lists many domains. Also advises 'Call this FIRST when you have many tools available'. Does not explicitly mention when not to use, 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 indicate readOnly, idempotent, non-destructive, open-world. The description adds behavioral specifics: fans out across multiple sources, notes patent API sunset (May 2025) and soft-fail, describes output structure with URIs and sorted fundamentals.

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-organized, starting with example queries and ending with output specifics. Could be slightly trimmed, but all sentences are informative.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description fully explains return fields, limitations (name not supported, patent sunset), and parallel execution. Sufficient for an agent to understand behavior and results.

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

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

Schema covers both parameters with descriptions. The description reinforces inputs: 'Pass ticker "AAPL" or zero-padded CIK "0000320193" — names not supported'. Adds practical guidance beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific sources and return fields. It distinguishes from siblings like 'resolve_entity' for name-based lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and instructs to use resolve_entity first if only a name is available. Example phrasings clarify typical user intents.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not introduce new behavioral traits beyond what annotations provide. No contradiction.

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

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

Two sentences, no unnecessary words. Purpose is front-loaded, and each sentence adds value (what it does, when to use).

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?

Tool is simple (1 param, no output schema). Description covers purpose, usage, and param context adequately. No gaps given the tool's complexity.

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

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

Schema coverage is 100% and description adds minimal value beyond the schema's description of the 'key' parameter. Baseline 3 is appropriate.

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

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

Clearly states 'Delete a previously stored memory by key.' Verb (delete) and resource (memory) are specific. Distinguishes from sibling tools 'remember' and 'recall' by explicit pairing.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with related tools, providing clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it fetches the page (network call), extracts title/description/key links, and emits standard markdown, providing behavioral context 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?

Three sentences: purpose, process, use cases. No fluff, front-loaded with key action. Every sentence adds value.

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

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

Despite no output schema, description adequately describes output format ('standard llms.txt markdown format', 'single text blob ready to drop at site-root/llms.txt'). Covers purpose, process, output, and use cases entirely for a simple tool with good annotations.

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

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

Schema coverage is 100% (both url and max_links described). The description does not add extra meaning beyond schema; it implies url usage in the first sentence but doesn't elaborate further. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with specific verb and resource. It explains the process and distinguishes from siblings by being specific to llms.txt generation, not general AI visibility.

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

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

The description lists three concrete use cases (client site indexing, own project drafting, competitor auditing). It provides clear context for when to use, but does not explicitly exclude alternatives or mention when not to use.

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

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

Annotations already declare read-only, idempotent. Description adds behavioral info (returns specific fields, supports place name or lat/lng) but no deeper detail on auth or limits.

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 examples, no fluff.

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

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

Despite no output schema, description lists return fields. Missing pagination details but adequate for a simple query tool.

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

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

Schema has 100% coverage. Description adds examples and clarifies format for `near`, surpassing schema.

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

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

Clearly states it finds places/POIs near a location, with examples and fields returned. Distinguishes from sibling geocoding/route tools.

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

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

Provides context on when to use (finding places) and examples, but does not explicitly exclude alternatives like geocoding or routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing return values (latitude/longitude, normalized address, match type, match score) and mentions 'high-accuracy geocoding', providing behavioral context beyond annotations.

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

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

The description is concise (two sentences), well-structured with the key instruction front-loaded ('PREFER OVER WEB SEARCH'). Every sentence adds value with no unnecessary words.

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

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

Without an output schema, the description fully explains what is returned (lat/lng, full address, match type, match score) including match type values. Parameters are well-covered in the schema. The description is complete for a simple geocoding tool given the rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples and mentions the 'q' parameter via example queries but does not significantly enhance understanding beyond the schema's own descriptions for 'limit' and 'country'. It provides no additional semantics beyond what's in 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 converts addresses/place names to coordinates ('turning an address or place name into precise coordinates'), using specific verbs and resources. It distinguishes from siblings like here_reverse_geocode by focusing on forward geocoding.

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 'PREFER OVER WEB SEARCH', giving clear when-to-use guidance versus a common alternative. It provides example queries. However, it does not explicitly mention when not to use or alternatives like here_reverse_geocode for the reverse operation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is clear. Description adds useful behavioral information: 'Returns the normalized address, place title, and distance to the matched location'. No contradictions or extra behavioral traits beyond what annotations provide.

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

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

Two sentences: first states purpose, second states return values. Front-loaded with key information, no wasted words. Extremely 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?

Given the tool's simplicity (2 simple params, no output schema), the description fully covers its operation. It explains inputs and outputs adequately, with no missing context.

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

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

Schema coverage is 100%, and parameters are well-described in the schema. The description mentions coordinates and provides examples, but does not add new meaning beyond the schema properties.

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's purpose: 'Turn coordinates into the nearest street address (reverse geocoding)'. It provides an example query format and distinguishes from siblings by naming 'reverse geocoding' (as opposed to forward geocoding in here_geocode).

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 is evident from the purpose and example. It explains what the tool does and gives a concrete query example. However, no explicit when-not or alternative tool guidance is provided.

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

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

Annotations already indicate readOnly, idempotent, and no side effects. The description adds behavioral details: returns distance, travel times (with traffic, free-flow, delay), and turn count. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the key differentiator ('TRAFFIC-AWARE'), includes examples, and is concise with no wasted words.

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

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

Given high-quality annotations and schema, the description is complete. It explains return values (distance, times, turn count) and input flexibility. While no output schema exists, the description compensates 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?

Input schema has 100% coverage, so baseline is 3. The description enhances this with examples and clarifies that origin/destination can be place names or lat,lng, and transport_mode defaults. This 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 uses specific verbs ('routing and ETA') and clearly identifies the resource (HERE) and key differentiator (traffic-aware, real-time traffic ETAs). It distinguishes itself from sibling tools like here_geocode and here_reverse_geocode by focusing on routing with traffic.

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 (traffic-aware routing), includes examples, and mentions constraints (origin/destination can be place names or lat,lng). However, it does not explicitly state when not to use or name alternatives among siblings, though the differentiation from 'keyless routing' is implicit.

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 show readOnlyHint, idempotentHint, destructiveHint false. Description adds that it returns specific fields (id, type, params, etc.) and covers the 'active' scope and include_inactive behavior, enriching the 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 efficient sentences: first defines purpose and output, second provides usage context. No wasted words.

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

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

For a simple read-only tool with 1 optional parameter and no output schema, the description fully covers purpose, output fields, and usage guidance without 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%. The only parameter (include_inactive) is fully described in the schema; description adds no extra semantic value beyond what the 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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. Could be enhanced with explicit when-not-to-use, but current guidance is sufficient.

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

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

Discloses the claim_token flow for anonymous filing, the ability to later query resolution status, rate limiting (5/day), and the fact that it is free with no quota impact. All annotations are false, so no contradiction; 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?

Long but every sentence earns its place. Front-loaded with the core action, then use cases, exclusions, mechanics, and limits. Structured in a logical flow without redundancy.

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

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

Even with no output schema, the description covers all necessary context: return behavior (claim_token), rate limits, message length expectations, and the feedback lifecycle. No gaps remain for an agent to use this tool correctly.

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

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

Schema covers 100% of parameters with descriptions, but the description adds functional meaning: it explains how claim_token works and how to pass it, and instructs users to frame issues in terms of Pipeworx tools/packs, which maps directly to the context object fields.

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

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

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by scoping to this connection's tools, not generic querying or research tasks.

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

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

Provides explicit when-to-use guidance (bug, feature/data_gap, praise) and an explicit when-not-to-use exclusion for tools from other MCP servers, even naming the alternative action (file with that server). This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the data source (CF analytics-engine), caching (5min-1h), and the self-aggregating, no-PII nature, going beyond what annotations provide.

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: it starts with the tool's output, then lists use cases, then technical details. Every sentence is informative and earns its place with no redundancy.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description is complete. It explains the data source, caching, and usage context, leaving no gaps 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?

Schema coverage is 100% with the 'window' parameter already described. The description adds nuance about shorter vs. longer windows ('hot right now' vs. 'steady-state demand'), providing extra semantic value beyond the base schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, specifying the resource and action. It distinguishes from siblings like 'discover_tools' by focusing on real-time trending data.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and notes window behavior. It lacks explicit when-not-to-use guidance but provides clear context for appropriate use.

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

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

Annotations indicate readOnly, openWorld, and idempotent. Description adds rich behavioral context: monotonicity checks, partition sum, semantic anchor, partition filter, fill check, and that the tool does not execute trades. No contradictions with annotations.

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

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

Description is lengthy but well-organized with clear sections for each mode, backtick formatting, and concise explanations. Every sentence adds value, though could be slightly more condensed.

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

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

No output schema, but description thoroughly explains response structure (opportunities array, partition_check object, fill check details). Covers important edge cases (placeholder filter, low similarity skip, realizable edge) and directs to other tools for further steps.

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

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

Schema coverage is 100% for both parameters. Description adds meaningful context beyond schema (e.g., event slug vs URL, topic as seed question, mode behavior), justifying a score above baseline 3.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending scan, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also explains when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations. It details the three model families, response structure (by_segment), caching (1h at KV level), edge calculation (including slippage), and warnings like 'Market moved X.Xpp in 24h'. No contradictions with annotations (readOnlyHint, etc.).

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

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

The description is very long and detailed, covering model families in depth. While well-structured with clear sections, it is not concise; the verbosity may reduce quick readability for AI agents. Front-loading the main use case helps, but overall length is a downside.

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

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

Given the complexity (9 parameters, no output schema), the description is thoroughly complete. It explains output structure (by_segment, fed_note, diagnostics), how segments are calculated, and how filters work. No major missing pieces for an agent to understand the tool's operation.

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

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

Despite 100% schema coverage, the description adds significant meaning to parameters. For example, it explains the role of 'min_liquidity' and 'max_spread_pp' as tradeable-edge filters, provides default behaviors, and gives practical advice like bumping slippage for thin partitions. This goes well beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market prices. It explicitly says 'Built for "what should I bet on today"', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker with a specific 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?

The description implies usage for discovering betting opportunities but does not explicitly state when to use this tool versus alternatives. It includes context like caching and exclusion of Fed bets from ranking, but lacks direct comparison to siblings. Some implicit guidance is present, but no explicit exclusions or preferences.

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 as true/false, covering safety. The description adds significant behavioral context beyond annotations, including limits (60-day TTL), response structure (tracked, expired, snapshot_dates), and that decay numbers are from daily closes, not intraday.

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

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

The description is front-loaded with purpose, then details and limits. It is somewhat verbose but each sentence adds value. For a telemetry tool with a nested response, the length is justified.

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 adequately covers the response structure (tracked, expired, snapshot_dates) and limitations. It lacks precise field definitions for the time-series data but provides enough context for an agent to understand the output's purpose.

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

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

Schema coverage is 100% with descriptions for both days and window. The description adds context: 'lookback', 'snapshot family', and clarifies defaults (14, '1wk') and constraints (max 30, valid families). This adds meaning beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' with specific verb+resource (edge persistence and decay telemetry). It distinguishes from siblings like polymarket_edges by focusing on historical trends rather than current snapshots.

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

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

The description implies when to use: for analyzing edge persistence vs. freshness, by contrasting a fresh wide edge with a 3-week-old wide edge. However, it does not explicitly mention alternatives or when not to use this tool, though sibling differentiation is clear.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds crucial behavioral context: the risk of partial fills leading to unhedged directional positions, and details of what the tool returns (e.g., verdict, thin_legs, forced_directional_risk). No contradictions.

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

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

The description is somewhat long but highly informative; every sentence adds value. Front-loaded with core purpose then mode details. Minor length allows for comprehensive guidance.

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

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

Despite lacking an output schema, the description thoroughly enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs) and covers edge cases. Complete for a complex tool with two modes.

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

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

Schema coverage is 100%, but the description significantly enhances understanding: for 'side', it explains default logic; for 'size_usd', it clarifies interpretation for buys vs sells and basket meaning; for 'market' and 'event', it maps to modes. Adds substantial meaning beyond schema.

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

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

The description clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket), making its purpose unambiguous and differentiated from siblings.

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

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

Explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns against partial basket fills converting arb into unhedged positions, providing excellent usage boundaries.

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 safe read operation (readOnlyHint, destructiveness false). Description adds extensive behavioral context: safety fields (compatibility_warning, temporal_alignment), counters for dropped comparisons, and conditions for meaningful spreads. 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 long but every sentence adds value. Front-loaded with purpose and modes. Could benefit from more structured breaks (e.g., bullet points) but remains clear.

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

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

No output schema, but description thoroughly explains response structure and safety fields. Given combinatorial complexity (modes, compatibility, temporal alignment), it provides sufficient context for correct invocation.

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

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

Schema covers all 3 parameters with descriptions. Description adds value by listing the topic shortcuts, explaining override behavior, and clarifying format requirements for explicit tickers/slugs.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings by focusing on cross-venue comparison, not intra-venue arbitrage or 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?

Explicitly explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warning. Does not explicitly contrast with sibling tools like polymarket_arbitrage, but context makes the usage clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping per identifier and listing behavior, which is useful beyond annotations.

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

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

Three sentences, front-loaded with main functionality. Every sentence adds value: functionality, use case, and integration with siblings. 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 (one optional param, no output schema), the description covers all necessary aspects: how to use, when to use, scope, and pairing with related tools.

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

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

Schema coverage is 100% and the schema already explains the key parameter. Description restates behavior but does not add new semantic meaning beyond what the 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?

Explicitly states the tool retrieves a saved value or lists all keys. Clearly distinguishes from sibling tools 'remember' and 'forget' by name and 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?

Provides explicit guidance on when to use (look up stored context without re-derivation) and implicitly when not (use forget for deletion). Mentions scoping and pairing with remember/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?

Annotations already declare safe read-only behavior; description adds valuable specifics: mark_read affects future calls, returns source/citation_uri/payload, and notes feed persistence and pagination via limit. 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?

Five sentences, front-loaded with main action, then details in logical order. No redundancy each sentence adds unique value.

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

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

Despite no output schema, description covers return fields, filtering, pagination (limit), mark_read behavior, and even alternative access method. Sufficient for agent to use correctly.

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

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

Schema covers all 5 parameters (100% coverage). Description adds contextual examples (e.g., 'sec_8k' for type, ISO timestamp for since, default limit 50) and clarifies mark_read effect, moving beyond schema to enhance understanding.

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

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

Description clearly states action ('pull fired events'), resource ('subscription feed'), and key return fields (source, citation_uri, payload). Distinguishes from HTTP endpoint alternative, making purpose unambiguous.

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

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

Provides context that polling works fine and mentions an HTTP alternative for scripts/dashboards, but does not explicitly state when to use this tool vs sibling tools or 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 (readOnly, idempotent, etc.), the description details multi-source parallel calls, fallback mechanism, soft-fail for USPTO, and the return format including citation URIs.

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

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

Front-loaded with example queries, 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?

Despite no output schema, description fully explains the return structure (grouped changes, count, URIs). Covers all behavioral aspects for effective use.

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

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

Schema coverage is 100%, but description adds context: explains 'since' formats (ISO/relative), mentions recommended default, and clarifies 'value' accepts ticker or CIK.

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 specifies the tool fetches a change feed for a company from multiple sources within a time window. It provides example queries like 'what's new with X' and distinguishes from sibling 'entity_profile'.

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

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

Explicitly tells when to use this tool vs 'entity_profile', gives query examples, and describes fallback behavior between GDELT and GNews.

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

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

The description adds significant behavioral context beyond annotations: persistence scoped by identifier, 24-hour retention for anonymous, persistent for authenticated users. Annotations provide idempotentHint=true and destructiveHint=false, which are consistent. The description could mention overwrite behavior explicitly, but the idempotent hint suggests safe overwrite.

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?

Highly concise at four sentences, each adding unique value. Front-loaded with purpose, then usage guidance, then 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?

Covers storage behavior, scope, persistence, and pairing with siblings. No output schema needed for a write operation. Could mention size limits, but not essential for typical use. Completeness is adequate.

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

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

Schema coverage is 100% with good descriptions. The description adds value by providing concrete examples of keys (subject_property, target_ticker, user_preference) and values, enhancing the context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and resource 'data' as key-value pairs. The description distinguishes itself from sibling tools 'recall' and 'forget' by focusing on saving, not retrieving or deleting.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget for related operations. While it doesn't explicitly state when not to use, the context is clear. The description also clarifies retention policies for authenticated vs anonymous sessions.

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

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

The description goes well beyond the annotations. It discloses that each call 'cascades through several lookup endpoints internally' and that it 'replaces 2-3 manual lookups.' It explains graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and explicitly states that unresolved identifiers are listed under `unresolved` rather than omitted—a key behavioral detail not captured in annotations or schema.

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 longer than average, but every sentence conveys meaningful usage or behavior. It is structured with a clear opening (examples + core purpose), followed by 'SUPPORTED TYPES' and a graceful-degradation note. The density is justified by the tool's two distinct modes and the need to clarify identifier sources and fallback behavior.

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?

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly for both entity types: company yields CIK, ticker, company_name, LEI, FIGI, and ownership info; drug yields RxCUI, ingredient, brand, and a citation. It also covers failure modes (unresolved identifiers, GLEIF/OpenFIGI downtime) and input formats, making the tool fully understandable on its own.

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

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

Schema coverage is 100% with both parameters described, but the description adds meaning beyond those descriptions. It elaborates on the 'company' type by explaining the cross-source identity spine (CIK, ticker, LEI, FIGI, ownership) and for 'drug' type it lists the specific outputs (RxCUI, ingredient, brand, citation). This helps the agent understand what each type will produce, filling in semantic gaps the schema leaves.

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 usage examples ('What's the ticker for…' / 'find the CIK for…') and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes itself from siblings by noting it is a prerequisite for other tools and names the supported entity types (company, drug) with their identifier outputs.

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 a clear usage directive: 'Use FIRST whenever you have a name but need an ID.' It also details what input formats each type accepts and what outputs to expect. While it doesn't explicitly name alternative tools to use when you already have an ID, the instruction implies that scenario and the sibling list includes entity_profile as a likely follow-up, so the context is sufficiently 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 safety traits (readOnly, idempotent). The description adds behavioral detail: how it works (probes each entity with ai_visibility_check, ranks, surfaces extremes). However, it does not mention potential cost/rate limit implications of multiple probes.

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

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

Two sentences with no filler; the purpose and mechanism are front-loaded. Every sentence earns its place.

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

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

Despite lacking an output schema, the description sufficiently describes the return format (ranked list with score, confidence, signal density). All key aspects are covered.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: clarifies 'entities' ordering (first is subject), explains 'context' use for disambiguation, and notes default model for 'models'.

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

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

The description uses a specific verb ('compare') and resource ('AI visibility across multiple entities side-by-side'), and clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

It provides a clear use case ('competitive AI-marketing audits') and an example query, but does not explicitly state when not to use or mention 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 set safe, read-only, idempotent traits. The description adds crucial behavioral context: multi-source fan-out, bundlephobia's slow first measurement (5-30s), and the sources_failed field. No contradictions with annotations.

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

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

Packaged densely - three sentences cover purpose, usage, ecosystem scope, and edge cases. Could be slightly more concise (e.g., merge the first two sentences), but every sentence adds unique value.

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

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

Despite no output schema, the description lists all return fields and explains behavior during partial failures. It addresses complexity: multi-source, version defaults, ecosystem restriction, and performance caveat. Fully complete given the tool's sophistication.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds useful context: defaults to latest version when omitted, and confirms scoped packages are accepted. Slightly more than the baseline 3.

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

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

The description instantly communicates the tool's composite nature (deps.dev + bundlephobia), the specific question it answers ('is X safe / popular / small'), and the output summary fields. It distinguishes itself from any potential sibling tools that might do similar checks (e.g., 'deps.dev:version' for other ecosystems).

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

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

Explicit 'Use whenever...' instruction with example queries. Clearly states ecosystem limitation (NPM v1) and directs users to alternative tools for other ecosystems. Also describes graceful degradation for partial failures.

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 embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and offset verification, far exceeding the read-only/idempotent annotations.

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

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

Front-loaded with core purpose, then usage guidance, then technical details. Every sentence is informative and no fluff.

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

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

Despite no output schema, description clearly states return type (top-N passages with offsets and scores) and edge cases (truncation). Covers all needed context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no new information beyond the schema's parameter descriptions; it restates the text and query examples but doesn't clarify limit 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?

Clearly states semantic search inside a fetched record with specific examples (SEC 10-K body, article). Explicitly pairs with ask_pipeworx_grounded, distinguishing itself from siblings.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions alternative grounding tool, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate a non-read-only, non-destructive, open-world, and idempotent operation. The description adds context: subscription creation requires authentication, returns an ID, and details delivery constraints (SMS cap, webhook signing). 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 reasonably concise for the complexity, with clear sections for types and delivery. Every sentence adds value, though it is somewhat lengthy. Front-loaded with the core purpose.

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

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

Given no output schema, the description mentions returning the subscription ID. It covers types, parameters, delivery channels, and constraints. Lacks explanation of what happens on duplicate subscriptions or error scenarios, but still quite 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%, but the description significantly enhances understanding by providing concrete examples for each subscription type and detailed delivery options (e.g., phone verification, webhook secret). This goes well beyond the schema's property descriptions.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), and explicitly mentions returning the subscription ID. It distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides clear context such as the requirement for a Pipeworx OAuth account and the inability of anonymous/BYO users to persist subscriptions. Lists supported types with examples but does not explicitly state when not to use this tool or recommend alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: it returns example questions with exact tool+argument shapes from a live catalog, and lists categories. This fully describes behavior beyond annotations.

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

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

Every sentence adds value: starts with example questions, states purpose, lists categories, gives usage instructions. No fluff, well-structured, 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?

With no output schema, the description fully covers return format (category-bucketed examples with tool+argument shape). It also mentions live catalog and meta-tools. Annotations cover safety. Complete for a discovery tool with one optional parameter.

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 reaffirms the topic parameter's purpose and optionality but does not add new semantic information beyond the schema. It provides usage context, which is more relevant to usage guidelines than parameter semantics.

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

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

The description clearly states that the tool returns category-bucketed example questions about Pipeworx capabilities, with specific verb+resource and explicit differentiation from siblings like 'discover_tools' by positioning it as the onboarding entry point.

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 explains when to use this tool (first interaction, when unsure of capabilities, to learn meta-tools) and provides two usage modes: full spread with no arguments or focused with a topic. No exclusions needed, 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 indicate write operation with idempotency and non-destructive nature. Description adds value by clarifying ownership enforcement and that rows are deactivated (not deleted), with reference to 'recent_alerts' for historical availability.

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

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

Two concise sentences, front-loaded with key action. Every sentence provides essential information without redundancy.

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

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

For a simple tool with one parameter, description covers purpose, ownership, behavioral effect, and connection to historical data. No output schema needed.

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

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

Input schema has 100% coverage with one parameter 'id'. Description adds ownership context beyond schema, enhancing understanding.

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

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

Description clearly states 'Cancel a subscription by id', specifying the action and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explains ownership enforcement ('you can only cancel your own subscriptions') and side effects (deactivation vs deletion). Provides context on when to use, though no explicit alternatives.

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

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

The description goes well beyond the annotations by explaining key behavioral nuances: the distinction between could_not_verify (error) and unsupported (no source coverage), the verification_error field, the two processing paths, and the return format with verdicts and citations. This aligns with and enriches the openWorldHint and readOnlyHint annotations without contradiction.

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

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

The description is relatively long but well-structured: it front-loads purpose with examples, then details processing paths and critical caller guidance. Every sentence provides needed information for a complex tool, though it could be slightly more concise without losing value.

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

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

Despite no output schema, the description fully explains return values, verdict categories, error handling, and fallback behavior. It covers both main claim types and gives implementation details like pipeworx:// citations. This makes the tool self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, with both claim and tolerance_pct already well-described in the input schema. The description adds context about claim handling (e.g., exact percent-delta math for financial claims) but doesn't significantly advance parameter understanding beyond the schema, so it earns the baseline score.

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: natural-language claim verification against authoritative sources, with explicit example queries. It distinguishes itself from siblings by focusing on fact-checking and returning verdicts, and it details the two distinct processing paths (structured SEC EDGAR for company-financial claims, grounded pipeline for other claims).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It also explains that it replaces 4–6 sequential calls, indicating efficiency. However, it doesn't explicitly name alternative tools or state when not to use it, so it lacks full when-not guidance.

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