Opentopography

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

Description adds useful behavioral details beyond annotations: default model (free), BYO key for Anthropic, per-model return structure (score, confidence, signals, raw_response). Annotations already confirm read-only, idempotent, non-destructive; description complements without contradiction.

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

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

Two sentences, front-loaded with primary action and scoring, immediately followed by key details. Every sentence earns its place 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?

Despite no output schema, the description covers purpose, parameter nuances (default model, _apiKey usage for Anthropic), and return structure. Combined with rich annotations, the agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, and description adds value by explaining default model, free vs paid probing, and the return format. This goes beyond mere parameter listing.

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 probes LLMs for brand/topic knowledge and returns a visibility score. It verb+resource is 'probe... LLMs' and differentiates from siblings like 'scan_competitor_ai_presence' by focusing on scoring and per-model breakdown.

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 cases are provided: AI-marketing audits, pre-launch brand checks, competitive monitoring. No explicit when-not-to-use, but context is clear enough for an AI agent to infer appropriate scenarios.

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

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

The description discloses behavior beyond annotations: it routes to internal tools, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. Given that annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the added behavioral context is sufficient and useful.

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

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

The description is front-loaded with the key directive, then organizes supported domains, examples, and routing behavior efficiently. There is minor redundancy around 'even if web search could also answer it' and 'START HERE', but overall each section 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?

Considering this is a very broad query-router with no output schema, the description is complete: it explains what happens under the hood, when to use it, what kinds of questions it handles, gives examples, and specifies the citation-based return format. An agent has enough to select and invoke the tool correctly.

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

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

The input schema already documents the lone question parameter and its aliases at 100% coverage, so the description does not need to re-explain parameters. It adds value by providing a broad domain list and realistic example questions, helping an agent know what kind of natural-language input is appropriate.

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

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

The description clearly states the tool's function: it answers factual questions by routing them to one of 5,718 tools across 1,496 verified sources and returns a structured answer with citation URIs. This is a specific, actionable verb+resource description that differentiates it from web search and gives the agent a clear mental model.

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

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

Usage guidance is explicit and strong: 'PREFER OVER WEB SEARCH' for many listed domains, 'Use whenever the user asks...', and 'START HERE for most questions' with concrete examples. The only gap is that it does not distinguish between sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so the selection among those close alternatives is left 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?

Beyond the read-only/idempotent annotations, the description discloses genuinely operational traits: behavior may diverge from stable whenever a routing candidate is under live test, none is active now so it currently matches ask_pipeworx exactly, and results are compared against the stable router to decide merges. The sentence 'Falls back to nothing — this IS a full working router, just the experimental edge' explicitly rules out stub or partial behavior, which is exactly the kind of clarification an agent needs.

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?

Each of the four sentences carries distinct information — identity, current state, usage condition, and functional guarantee — with the core identity front-loaded. The historical detail about the candidate retired on outcome evidence 2026-07-26 is slightly extraneous but anchors the no-candidate-active claim in evidence rather than assertion.

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

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

For a complex beta variant with six parameters and no output schema, the description covers identity, equivalence to stable, current operational state, usage, and functionality guarantees, and defers response shape to ask_pipeworx. The only gap is that the core function of universal router relies on the reader already knowing what ask_pipeworx does; the tool never defines its own behavior in standalone terms.

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

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

Schema description coverage is 100%, so the required question and its aliases (q, text, input) are already fully documented in structured form. The description only adds a cross-reference that arguments are the same as ask_pipeworx, which is mildly useful for an agent familiar with the stable variant but does not elevate the baseline of 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 first sentence states a concrete identity and function: a beta version of ask_pipeworx, an identical universal router over the same 5,718 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx and other siblings (notably ask_pipeworx_grounded), so an agent can select it correctly before inspecting any schema.

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

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

It gives an explicit use condition — use it exactly like ask_pipeworx when you want the newest routing — and names the stable router as the comparison baseline, which implies the agent should prefer the stable variant when it does not want experimental routing. It does not enumerate when-not cases or other alternatives like ask_pipeworx_grounded, so the guidance is clear but not exhaustive.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behavioral traits: it extracts only from tool results, returns a refusal with specific reasons when data doesn't directly answer, and incurs an extra LLM call. This is precisely the kind of context annotations don't capture and is essential for trust in high-stakes use.

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 serves a purpose: purpose, mechanism, return contract, use case, and cost trade-off. It is well-structured and front-loaded with the core value. A slight trim would be possible, but the density is justified given the tool's complexity.

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

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

There is no output schema, yet the description fully specifies the success return shape and all refusal reason enum values. It covers use cases, reliability guarantees, relation to sibling, and cost implications. For a tool with this much routing complexity, nothing necessary is missing.

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

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

Schema description coverage is 100%, with all parameter aliases and the primary 'question' parameter already documented. The description doesn't add parameter-level semantics beyond what the schema provides. It earns the baseline 3 for not needing to compensate.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates itself from sibling ask_pipeworx by explaining the same routing but strict extraction behavior. An agent can immediately understand what this tool does and how it differs from alternatives.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the sibling alternative and the trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is direct and actionable.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing safety mechanisms (low-confidence blocking, closed market handling, wide-spread liquidity warning), resolution-rule risk parsing, resolver contract, parent event extractor, and news fallback fields. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. While every sentence adds value, the length could hinder quick scanning. A slightly more condensed version might be beneficial, but it balances detail and organization well given complexity.

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

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

Despite no output schema, the description comprehensively explains return shapes (market, analysis, evidence), resolver contract, parent event handling, news field details, error conditions (low confidence, closed markets), and resolution-rule risk. It covers all necessary context for an agent to use the tool correctly.

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

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

All three parameters are described with clear semantics beyond the schema. The 'market' parameter explains acceptable formats (slug, URL, question text), 'depth' defines quick vs thorough and default, and 'include_raw' clarifies when to enable. Schema coverage is 100%, and description adds meaningful context.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and details the process (resolve, classify, fan out, return evidence packet + comparison). It distinguishes from siblings like polymarket_arbitrage by framing use cases like 'should I bet on X'.

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 usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes examples of fan-out scenarios (BTC bet, Fed bet, etc.) but lacks explicit when-not-to-use or alternative tool mentions. However, the context is strong enough to infer 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 already declare read-only and idempotent. Description adds details on data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and return format with citation URIs. 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?

Concise at ~120 words, uses bullet-like structure with quoted trigger phrases. Front-loaded with core purpose, every sentence adds value. No redundant or missing information.

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

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

Given low complexity (2 params, no output schema) and rich annotations, description covers data sources, return format, sorting, and efficiency gain. Completely sufficient for agent to understand usage and outcomes.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining what each type pulls (company: financials; drug: adverse events, trials) and provides concrete examples for the values parameter. Reinforces constraints with examples.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, with specific trigger phrases. It distinguishes from sibling tools like entity_profile by explicitly advocating over 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?

Explicitly states when to use (comparisons like 'which is bigger') and warns against sequential lookups. Provides examples of triggers and emphasizes preference over 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=true and destructiveHint=false, indicating a safe read operation. The description adds value by listing specific dataset identifiers (SRTMGL1, etc.), providing context beyond annotations without contradiction.

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

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

The description is a single sentence with no waste, front-loading the main purpose and listing examples. It is optimally concise for the tool's simplicity.

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 no parameters and an existing output schema, the description is complete. It clearly states what is listed (identifiers) and provides concrete examples, leaving no ambiguity.

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 no parameters (100% coverage), so the description does not need to explain parameters. The baseline is 4 for a zero-parameter tool, and the description adds no additional parameter info, which is appropriate.

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

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

The description clearly states the tool lists supported global DEM dataset identifiers, using a specific verb ('list') and resource ('supported global DEM dataset identifiers'). It distinguishes itself from sibling tools like 'dem' by focusing on identifiers.

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 fetching available DEM dataset identifiers but provides no explicit guidance on when to use this tool versus alternatives (e.g., 'dem' tool). No exclusions or prerequisites are mentioned.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description builds on these by revealing how the tool decomposes questions, routes to 5,718 tools in parallel, returns findings packets with verbatim evidence/confidence/source/fetched_at/citation, explicitly reports gaps[], and never invents answers. It discloses timing (15-60s, up to 90s for thorough), hop semantics, contradiction detection, semantic excerpting behavior, and citation resolvability. This is rich behavioral context well beyond the structured annotations.

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

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

The description packs a lot of valuable information, but it is a dense, unbroken block of text approaching 300 words. Information like account requirements, tier pricing, timing estimates, and gap/contradiction mechanics are all threaded together without paragraph breaks or scannable structure. Every sentence does earn its place, but the wall-of-text format hurts usability for an agent trying to quickly extract routing decisions.

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

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

For a 2-parameter tool with 100% schema coverage and no output schema, the description covers: prerequisites, auth requirements, what it does, when to use it, when not to use it (with named alternatives), latency expectations, failure behavior (gaps[]), citation semantics, and multi-hop behavior. There's no significant gap an agent would stumble on when selecting or invoking this tool. The lack of output schema is compensated by the detailed findings-packet description.

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 covers 100% of parameters with descriptions. The description adds real value by explaining the depth enum impact in prose already mirrored in the schema: what 'standard' and 'thorough' actually mean in terms of hops, gap recovery, and contradictions. The justification for 4 rather than 3 is that the description explains the user-visible consequences of choosing depth values (e.g., 'thorough' requires paid plan, up to 90s latency), which is operational meaning not present in the schema's structural definitions.

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

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

The description clearly states this is grounded multi-source research across 1496 structured data sources in one call, explicitly distinguishing it from open-web search. It names the sibling tools it competes with (ask_pipeworx) and gives concrete example queries. The scope is specific: broad/multi-part questions over structured 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 gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use with named alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also covers account prerequisites, paid-tier requirements, and depth-level selection criteria, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnly, idempotent, not destructive. The description adds that it returns a URL to GeoTIFF, but does not detail scaling, limits, or performance. With annotations covering safety, the description provides marginal additional behavioral context.

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

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

The description is a single concise sentence with no wasted words, but it omits important details about parameters and usage. It is appropriately front-loaded but could be expanded without becoming verbose.

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

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

Given the low schema coverage and 6 parameters (5 required), the description is too minimal. It does not explain dataset options, coordinate order, units, or response structure beyond 'URL to GeoTIFF'. The output schema exists but the description does not leverage it.

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 only 17%, with only the 'format' parameter described. The description does not explain the bounding box parameters (east, west, north, south) or the required 'dataset' parameter, leaving most parameters opaque.

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 a DEM raster for a bounding box as a URL to GeoTIFF. It uses a specific verb and resource, and distinguishes from sibling tools like point_elevation which queries single points.

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?

No guidance on when to use this tool versus alternatives, such as point_elevation for single points or other raster tools. No context on prerequisites or when not to use.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds context that results are 'ready to call directly' and 'top-N most relevant,' which aids agent understanding without contradicting annotations.

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

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

Front-loaded with purpose and use cases; every sentence provides value. Slightly verbose with domain examples but likely helpful for context.

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, full schema coverage, no output schema, and no nested objects, the description adequately covers return format (schemas included) and usage suggestions.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases but does not add significant meaning beyond what the schema's descriptions already provide.

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 function: 'Find tools by describing the data or task.' It uses specific verbs and resources, and immediately distinguishes itself from sibling tools by being the only discovery tool.

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

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

Explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set.' Provides concrete examples like 'look up FDA drug approvals' and 'analyze housing market trends'.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds contextual details: fans across multiple sources, specifics of return fields, patent sunset soft-fail, and fallback mechanisms. Further detail on rate limits or error handling would push to a 5.

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 front-loaded with examples and a clear one-liner. Each sentence contributes value (sources, return fields, limitations). Could be slightly more concise without losing clarity.

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

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

Covers multiple data sources, return fields, patent sunset, and fallback. No output schema, but description details return structure adequately. Could mention error handling or rate limits for completeness.

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

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

Schema coverage is 100%, so the description doesn't need to add much. It does clarify that 'value' accepts ticker or zero-padded CIK and that 'names not supported', which aligns with schema. No additional semantics beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states 'full cross-source profile of a US public company in ONE parallel call' and provides example queries like 'tell me about X' and 'company profile for Microsoft', making the purpose specific and distinct from sibling tools.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack lookups when holistic view is needed' and warns that names are not supported, directing to use 'resolve_entity' first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about what is deleted and when, without contradicting annotations.

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

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

Two sentences, front-loaded with action, no waste. 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?

For a simple tool with one param and destructive annotation, the description covers purpose, usage guidance, and sibling pairing. No output schema required.

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

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

Schema coverage is 100%, so baseline 3. The description does not add meaning beyond the schema's 'Memory key to delete'.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key', which is specific and distinguishes from siblings like 'remember' and 'recall'.

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

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

Includes three explicit use cases (stale context, task done, clear sensitive data) and recommends pairing with siblings, though it lacks explicit when-not to use or prerequisites like key existence.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details like fetching the page, extracting title/description/key links, and emitting markdown format. It does not contradict annotations and provides useful extra context beyond the structured data.

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

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

The description is two concise paragraphs: the first explains the tool's action and output, the second lists use cases. No superfluous words, and critical information is front-loaded. 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?

For a tool with 2 simple parameters and no output schema, the description fully covers its behavior: it fetches, extracts, and emits a single text blob. The output format and deployment location are clearly stated. No gaps remain for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% (both parameters described in schema). The description mentions 'for any URL' and 'max link entries' implicitly, but adds little new meaning beyond what the schema already provides. Baseline score of 3 is appropriate given high coverage.

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

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

The description uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource (llms.txt file for a URL). It distinguishes from sibling tools by focusing on AI indexing and a specific output format, making 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 explicitly lists three use cases: client site indexing, personal project drafting, and competitor auditing. While it doesn't mention when not to use or provide alternative tool names, the stated use cases give clear context for appropriate usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the baseline for behavioral safety is covered. The description adds value by stating the exact return fields, particularly last_fired_at and fire_count, which are not obvious from the tool's name. However, it does not detail pagination, ordering, or potential rate limits, which would push it to 5.

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: the first states purpose and output, the second provides usage guidance. Every word is meaningful; no redundancy or filler. The description is front-loaded with the core action and immediately useful information for an AI agent.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is substantially complete. It covers purpose, return fields, and usage context. Minor omissions like default limit or ordering could exist but are not critical given the tool's simplicity. The combination with annotations provides a solid understanding.

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 has 100% description coverage for the single parameter include_inactive, so the baseline is 3. The description does not add any additional semantic information beyond what the schema already provides (e.g., it doesn't explain default behavior or implications of the parameter). Hence, a 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 uses the specific verb 'list' and resource 'subscriptions' and clarifies it returns the caller's active subscriptions. It also lists the returned fields, making the tool's purpose crystal clear. The guidance 'to find an id to cancel' implicitly distinguishes from sibling tools like subscribe and unsubscribe, giving it excellent purpose clarity.

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 the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to sibling tools (subscribe, unsubscribe) and provides clear usage context. No ambiguity about when to employ this tool versus 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 provide no safety hints, so the description carries the full burden. It discloses rate limits (5 per identifier per day), non-quota behavior (free), the claim_token workflow for later status checks, and the fact that filing without an account still works. No contradictions with annotations.

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

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

The description is long but dense, with every clause serving a purpose. It front-loads the core purpose in the first sentence and then packs usage guidance, exclusions, workflow, and rate limits efficiently. Slightly more verbose than strictly necessary, but no filler.

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 dual-mode behavior (filing new feedback vs. checking an existing claim) and lack of output schema, the description covers all necessary operational aspects: return values, restrictions, rate limits, and scope boundaries. It is fully self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds crucial semantics beyond the schema: telling users not to paste end-user prompts, emphasizing Pipeworx tool names in the message, and explaining the claim_token's role as a future lookup. This enriches rather than merely repeats schema info.

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

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

The description opens with a specific verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than questions, and even mentions alternative reporting paths.

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 scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use (different MCP server) with instructions to file elsewhere. It also gives a heuristic for identifying Pipeworx tools, making the decision process concrete.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. No contradictions.

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

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

Three sentences: main purpose, three bullet-free use cases, technical details. Every sentence adds value, no redundancy. Front-loaded with the core function.

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

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

Given no output schema, description plausibly describes output (top tools, packs, volume). Context signals indicate simplicity (1 param, no required). Could detail response structure, but sufficient for effective use.

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

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

Schema covers 100% of parameter (window enum). Description adds semantic guidance: shorter windows for hot trends, longer for steady-state demand, which improves understanding beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window. The verb 'Returns' and specific resource 'what other AI agents are calling' distinguish it from sibling tools like 'discover_tools'.

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

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

Three explicit use cases are provided (discovering hot sources, confirming canonical choice, seeing alignment). Includes guidance on window selection (shorter for hot, longer for steady-state). Lacks explicit exclusions 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 declare readOnlyHint and idempotentHint. The description adds that the result is a URL (not a direct value) and is a 1-pixel raster, which is 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?

A single, front-loaded sentence with no filler. Efficiently communicates the core behavior and an alternative.

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?

Output schema exists, so return values are covered. However, missing dataset guidance and coordinate details may confuse agents. Adequate but not exhaustive.

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 0%, so the description should compensate. It does not explain any parameters (e.g., valid datasets, coordinate format). Only schema examples provide minimal guidance.

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 elevation for a point, specifying it provides a 1-pixel raster URL. It distinguishes itself from opentopodata for direct values, making the purpose unambiguous.

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

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

It advises using opentopodata for direct point values, indicating when not to use this tool. However, it doesn't cover other scenarios or prerequisites.

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

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

The description discloses extensive behavioral traits beyond the annotations: it walks child markets, checks ordering, computes partition checks, uses Jaccard similarity for cross-event pairs, filters placeholders, and performs a fill check against live CLOB depth. Annotations already indicate readOnly, idempotent, non-destructive, but the description adds rich context. No contradictions with annotations.

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

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

The description is detailed and well-structured, with clear sections for each mode and fallback behavior. While it is somewhat verbose, every sentence adds value and contributes to understanding. It could be slightly shortened, but the structure is effective for an AI agent.

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

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

Given the complexity of the tool and the absence of an output schema, the description covers the input modes, behavior, response structure (opportunities[], partition_check, fill check), and trade recommendations. However, it does not fully specify the exact structure of the response object, leaving some ambiguity. Still, it provides sufficient information for an agent to use the tool effectively.

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

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

While the input schema already has 100% coverage with descriptions, the tool description adds significant meaning: it explains the two modes (trending_scan with no args, event mode, topic mode), the semantics of event slugs and topic seed questions, and the internal logic (e.g., semantic anchor, partition filter). This goes well 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies the resource (Polymarket arbitrage), the method (monotonicity and partition checks), and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on these specific arbitrage types.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises on alternatives: 'For custom sizing use polymarket_fill_risk'. This clearly helps the agent decide when to invoke this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds substantial behavioral context: caching details (1h at KV level), response structure (by_segment with three segments, diagnostics, fed_candidates), edge calculation (net of slippage, Kelly fractions capped at 0.25, market move warnings), and model internals (lognormal barrier, GDELT ratio, partition overround with corrections). This goes well beyond the annotations.

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

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

The description is dense and thorough, packing a lot of information into multiple paragraphs. It is front-loaded with the core purpose and gradually adds depth. While not overly verbose, some sections could be streamlined. Overall, every sentence contributes to understanding, but the length could be trimmed for a quicker read.

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

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

Given the high complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output structure in detail (by_segment, diagnostics, Fed bets), model logic, and edge components. Without an output schema, the description fully covers return values and behavior, leaving no significant gaps for an agent to interpret.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds marginal value by explaining knobs like min_liquidity and max_spread_pp in context, but mostly reiterates what's already in the schema. It does not significantly enhance understanding beyond the schema descriptions, so baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and identifies the resource (Polymarket markets). The description distinguishes itself from sibling tools by explaining its unique data source and model families, making clear what this tool does differently.

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 frames the tool for 'what should I bet on today' and explains that it avoids paging through hundreds of markets. It mentions that Fed bets are excluded from ranking and notes caching behavior. However, it does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker, leaving some implicit guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), meaning of decay_pp_per_day, and data limitations (daily closes, not intraday). 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 lengthy but well-structured, starting with purpose, then detailing response and limits. Every sentence contributes meaningful information. Could be slightly trimmed, but overall effective.

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

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

Given no output schema, the description thoroughly covers return values (tracked, expired, snapshot_dates) and their fields. It also explains parameters, data limitations, and edge cases (gaps in snapshots). Fully contextually complete for agent 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%, and the description adds value by specifying default values (14 days, '1wk') and range for 'days' (2-30). It clarifies the meaning of 'window' as snapshot family. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('tracks' / 'answers') and resource ('edge persistence and decay') and distinguishes itself from similar tools like polymarket_edges (which provides snapshots) by focusing on time-series analysis.

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

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

The description provides explicit context on when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'. It sets expectations with limits (60-day TTL, daily data). However, it does not directly compare to sibling tools or specify 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral context: walks the order-book ladder, returns fill details, verdicts (clean/degraded/cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

Description is lengthy but every sentence adds necessary detail. Front-loaded with core purpose. Could be slightly trimmed, but overall well-structured for the complexity.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains return fields, usage contexts, and edge cases. Without an output schema, the description compensates by listing all return values.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining how size_usd is interpreted differently for single-market vs basket, and how default side works in basket mode. Provides context beyond schema definitions.

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

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

Description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific details. Differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.

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

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

Annotations already mark the tool as read-only and non-destructive, but the description goes far beyond that by disclosing matching behavior, compatibility codes, unclassified-leg exclusion rules, skipped cross-type/cross-subtype counters, and temporal alignment semantics. It tells the agent exactly what results mean and which pairs require caution.

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

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

The description is long but well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and dense, non-redundant detail. It front-loads the core purpose before diving into codes and counters, and every major section earns its place given the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: raw probabilities, top_spreads_pp, compatibility_warning/codes, skipped categories, low-confidence pairs, and temporal alignment are all covered. The tool is complex, and the description leaves no critical behavior undocumented.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains that topic is a pre-mapped shortcut list and that kalshi_event_ticker and polymarket_event_slug override the mapped side for custom pairings. This relationship is not fully visible in 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 names a specific verb-resource pair: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also clearly distinguishes the tool from related siblings by framing it as a spread/comparison tool rather than an arbitrage or edge-finder, and it disambiguates its two internal modes.

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 clear context on when to use the tool, including the two modes and when to prefer explicit pairings over pre-mapped topics. It warns that pre-mapped shortcuts are often not tradeable and that compatibility warnings must be read, though it does not explicitly name sibling alternatives or state when not to use this tool.

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

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

Adds scoping and listing behavior beyond annotations (readOnlyHint, idempotentHint), 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?

Concise at 3-4 sentences, each adding value, with no redundant content.

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

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

Complete for a simple retrieval tool with one optional parameter, covering usage, scoping, and pairing with siblings.

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

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

Schema already describes the key parameter fully (100% coverage); tool description reinforces but adds little new.

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?

States precisely it retrieves a saved value or lists all keys, distinguishing it from siblings like remember and forget.

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

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

Provides examples of when to use (stored context) and scoping, but lacks explicit when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint=true (no write operations), yet the description states that setting mark_read:true flags events as read, which is a state change. This contradicts the readOnlyHint annotation, so score is 1.

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 (about 100 words), front-loaded with the core purpose, and each sentence adds necessary context 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 tool with 5 optional parameters and no output schema, the description covers usage scenarios, behavior of mark_read, and an alternative access method. However, the annotation contradiction undermines overall completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read and providing an example for type filtering, but does not add details for all parameters.

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

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

The description clearly states it pulls fired events from a subscription feed, and it specifies the returned fields (source, citation_uri, raw payload). It distinguishes itself from siblings by focusing on alert retrieval with specific filtering options.

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 notes that polls work fine and provides an alternative REST endpoint for scripts/dashboards. It also explains that setting mark_read:true affects subsequent calls. However, it does not explicitly state when not to use this tool versus others.

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 expands on annotations (readOnly, idempotent, openWorld) by detailing parallel fan-out to multiple sources, fallback logic, and date handling. It explains return format and citation URIs, providing behavioral context beyond structured fields.

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

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

The description is a single dense paragraph that front-loads use cases and then efficiently covers sources, parameters, and return format with no wasted words. 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 no output schema, the description thoroughly explains the return value (changes grouped by source, total_changes, citation URIs) and handles edge cases (fails, fallbacks). The tool has 3 fully described parameters, and the description covers all necessary 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?

With 100% schema coverage, the description still adds significant value: for 'since' it explains ISO date and relative shorthand with examples, for 'value' it specifies ticker or CIK format, and for 'type' it notes only 'company' supported. This goes 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?

The description clearly states the tool's purpose as a change feed for a company within a time window, with specific examples like 'What's new with X' and details on data sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool entity_profile for static profiles.

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

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

The description provides explicit when-to-use guidance with example queries and directs to use entity_profile for static profiles. It also clarifies fallback behavior for GDELT→GNews and soft-fail for USPTO, giving 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?

Adds persistence details beyond annotations: authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradiction with annotations.

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

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

Three sentences, front-loaded purpose, 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?

Adequate for a simple storage tool; could mention return behavior but not required given simplicity.

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 100%; description adds example key patterns but no additional semantic detail 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?

Clear verb 'Save' with explicit resource 'data the agent will need to reuse later'. Distinct from siblings recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and pairs with recall/forget for retrieval/deletion.

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

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description reveals key runtime behavior: ambiguity returns `figi_candidates` rather than asserting, unresolved identifiers are listed under `unresolved` instead of omitted, enrichment degrades gracefully when GLEIF/OpenFIGI are down, and each call cascades internally through several endpoints.

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

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

The description is dense and heavily parenthetical, and some phrases are editorial ('which is the correct answer...'), but it is well front-loaded with the purpose and use trigger, then organizes the two supported types with enough detail to justify its length.

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 still explains the main return fields (CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, citation), the ambiguity fallback, the `unresolved` field, and graceful degradation. This is sufficient for an agent to call the tool and interpret common outcomes 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?

Although schema coverage is 100%, the description substantially extends the schema: it lists accepted input forms for `value` (ticker, CIK, ISIN, company name, brand/generic), explains the ISIN-to-LEI path for non-US issuers, and gives explicit formatting guidance such as passing the issuer exactly as printed and excluding trailing security-class words.

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 user phrasings ('What's the ticker for…' / 'find the CIK for…') and immediately states the verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also scopes supported types ('company', 'drug') and contrasts with downstream tools, making it easy to distinguish from siblings like entity_profile or 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 gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' and clarifies that it 'replaces 2-3 manual lookups.' It does not name a specific alternative to switch to when the user does not need an ID, so there is a slight gap in when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds behavioral details: probes each entity, ranks by score, returns score/confidence/signal density. No contradictions. Good additional context beyond annotations.

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

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

Two sentences: first states core action, second adds use case and return info. No redundant information, front-loaded with key action. Efficient and 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?

With no output schema and 4 parameters, description covers purpose, process, and return contents. Missing details on output structure (e.g., exact fields, types) and constraints (e.g., entity count range). However, sufficient for agent to use tool correctly.

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

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

Schema description coverage is 100%, but the description adds extra meaning: entities first entry treated as 'subject', rest as competitors. Also notes models default and context usage. Adds value beyond 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes from sibling tools like ai_visibility_check by specifying multiple entities and competitive audit use case. Example question adds concrete context.

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

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

Description explicitly states 'useful for competitive AI-marketing audits' and implies when to use. However, it does not explicitly state when NOT to use this tool over alternatives (e.g., single entity comparison), though sibling list suggests ai_visibility_check exists for single probes.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds: composite fan-out, partial failure degradation, bundlephobia first measurement delay (5-30s), sources_failed reporting. No contradiction.

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

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

Description is detailed but every sentence adds value. It front-loads purpose and then elaborates. Could be slightly more structured but remains clear and not redundant.

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 complexity (composite, partial failures, timing), description covers all key aspects: return fields listed (summary block, advisories, links, alternatives), behaviors explained. No missing critical info.

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

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

Schema coverage is 100% with descriptions. Description adds value by noting scoped packages accepted and version defaults to latest, which is 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?

Description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia, with verb 'scan' and resource 'dependency'. It distinguishes from siblings by specifying NPM-only scope and mentioning alternative 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 usage triggers given ('is X safe / popular / small', 'what does adding lodash cost me'). Exclusions stated: NPM only in v1; other ecosystems fall under deps.dev:version directly. Provides clear when-to-use and when-not.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds critical behavioral details: BGE-base-en embeddings, cosine scoring, 500-char overlapping windows, 200K char cap with truncation flag, output includes offsets and scores. No contradictions.

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

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

Three compact sentences that efficiently convey purpose, usage, and implementation detail. Front-loaded with the core action. 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 return format (top-N passages with offsets and scores). Covers all inputs, limitations, and technical details. No missing context for a search tool with clear 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 description coverage is 100%, so baseline is 3. Description adds value beyond schema by providing usage examples for 'query' and clarifying the truncation behavior for 'text'. This extra context raises it to 4.

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

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

Clear verb-resource pair ('search inside a fetched record') with concrete examples (SEC 10-K, article). Distinguishes from sibling tools by naming ask_pipeworx_grounded as a complementary tool.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Provides alternative pairing with ask_pipeworx_grounded. Offers concrete use-case guidance.

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

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

The description fully discloses behavioral traits: non-read-only, idempotent, non-destructive. It details OAuth requirement, delivery channel specifics (feed always on, email/sms/webhook with constraints like phone verification, SMS cap, webhook signing and auto-disable). 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 well-structured and front-loaded with purpose and return value. It is somewhat lengthy but every sentence provides value, with examples and specific details. Minor redundancy could be trimmed.

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

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

Given the complexity (multiple types, delivery options, no output schema), the description is complete: it explains return value (subscription ID, webhook secret), behavior (idempotent, non-destructive), and all constraints. No gaps remain.

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

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

Schema coverage is 100%, and the description adds substantial meaning: examples for each subscription type's params, delivery channel formats, and constraints (e.g., webhook signing secret returned once). This goes 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 tool creates a proactive monitoring subscription and returns a subscription ID. It lists specific event types and delivery channels, and distinguishes it from sibling tools 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?

The description explains when to use (setting up proactive monitoring) and prerequisites (Pipeworx OAuth account). However, it does not explicitly compare to alternative tools or state when not to use, leaving some ambiguity for the agent to infer.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds value by specifying that it returns categorised example questions with exact tool+argument shapes drawn from a live catalog, and that it can be called with no arguments or a topic. No contradictions.

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

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

The description is well-structured, starting with alternative phrasings, then stating purpose, followed by return value and usage. Each sentence adds value, though it is slightly lengthy at about 150 words.

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

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

Given no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shape) and usage (no args vs topic). It covers the necessary context for an onboarding 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?

The schema covers the single parameter 'topic' with 100% coverage. The description adds concrete examples like 'finance', 'pharma', 'betting', providing practical guidance beyond the schema's description.

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 as an onboarding entry point that returns category-bucketed example questions, including specific topics and tool shapes. It distinguishes itself by being the first tool to use when the agent doesn't know Pipeworx's capabilities.

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 instructs to use this tool first when the agent doesn't know Pipeworx's capabilities or wants to learn meta-tools. It also explains the optional topic parameter for focus. However, it doesn't explicitly mention when not to use it, though the context implies alternatives.

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

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

Annotations indicate non-readOnly, non-destructive, but idempotent. The description adds critical behavioral context: the row is deactivated (not deleted) and historical events remain via recent_alerts. This goes beyond annotations and clarifies the actual effect.

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

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

Two sentences, no wasted words. The first introduces action and constraint, the second explains the behavioral outcome. Perfectly front-loaded and efficient.

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

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

For a simple tool (1 param, no output schema), the description covers purpose, usage constraint, and what happens to the row. It also informs the user about where to find historical data (recent_alerts). No gaps.

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

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

The only parameter 'id' has a description in the schema ('Subscription id (uuid) returned by subscribe.'). The description adds a phrase 'by id' which is redundant but the mention that the id comes from subscribe is helpful. With 100% schema coverage, baseline is 3, and little extra value 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?

Clearly states the action 'Cancel a subscription by id.' It identifies the resource (subscriptions) and distinguishes from its sibling 'subscribe'. However, it does not explicitly differentiate from other related tools like '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?

The description states that ownership is enforced, implying you can only cancel your own subscriptions. It provides a key constraint but does not mention when not to use the tool or suggest 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 declare readOnly/openWorld/idempotent, but the description adds critical semantics beyond that: the distinction between could_not_verify (check failed, not evidence) and unsupported (no source covered), the default tolerance cap of 5%, and the exact verdict list. These details prevent misinterpretation of results, exceeding annotation coverage.

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?

Although lengthy, the description is front-loaded with query examples and every sentence serves a purpose: routing logic, return format, error semantics, and efficiency gains. It avoids fluff and maintains a clear logical flow from invocation to output interpretation.

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 takes on the burden of explaining return values, and it does so thoroughly: verdict types, grounded/structured value with citation, reasoning, and even verification_error structure details. It also explains the fallback pipeline and covers edge cases, making it complete for a tool with this 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 already covers 100% of parameters with descriptions, so baseline is 3. The description adds extra value by explaining tolerance_pct's override behavior and giving a concrete use case (set 1–2 for hallucination detection), which the schema does not convey. Claim examples also illustrate expected input formats, slightly enriching 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 a specific verb+resource: 'natural-language claim verification against authoritative sources,' with concrete example phrasings ('is it true', 'fact check'). It clearly distinguishes the tool's niche from siblings by positioning it as a fused multi-step claim checker, and mentions replacing 4–6 sequential calls, making its purpose unmistakable.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further provides routing guidance for company-financial claims vs all other factual claims, and gives actionable tolerance_pct advice for hallucination detection. No alternatives are named, but the context is unambiguous.

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