Geodistance

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds cost context (free Workers AI vs BYO Anthropic), return structure (score, confidence, signals, raw_response, combined view), and that probing multiple models is possible.

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

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

Three sentences front-loaded with the core action and output, followed by use cases and parameter hints. No wasted words; every sentence adds value.

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

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

Despite no output schema, the description clearly outlines the per-model return fields and combined view. Covers all required and optional parameters, use cases, and cost implications, making the tool fully understandable.

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

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

Schema already provides 100% description coverage for all parameters. The description reinforces defaults (Workers AI) and optionality of `context`, adding marginal value 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?

Clearly states it probes LLMs for brand visibility and scores 0-100 per model. Lists specific use cases (AI-marketing audits, pre-launch checks, competitive monitoring), distinguishing it from sibling tools like scan_competitor_ai_presence.

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 describes when to use (AI-marketing audits, etc.) and explains the condition for using `_apiKey` (only if probing Anthropic). Could be improved by mentioning when not to use or direct alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is carried by structured metadata. The description adds useful behavioral context on top: the tool automatically routes the question to one of 5,596 tools, fills arguments itself, and returns answers with stable pipeworx:// citation URIs. This tells the agent what to expect beyond the read-only nature, though it still does not fully explain what happens when no source matches.

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 front-loaded with the most important routing decision, and it packs a long list of covered domains, trigger phrases, and examples into one tight block. It is longer than strictly necessary, but each sentence carries information an agent needs for selection and invocation. The trailing ramble (citing the grounded variant) is loosely glued to the main description but still serviceable.

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 that routes to thousands of sources based on a single free-text question, the description covers the critical contextual points: when to use it, how to phrase the question, what kind of answer it returns (structured with citations), and which alternatives to prefer. The main gap is the absence of any mention about error behavior, rate limits, or how the answer is presented when the tool fails to find a source, but this is acceptable given the largely open-world, pick-a-tool design.

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% because the single question parameter and its aliases are fully documented in the schema itself. The description complements the schema by clarifying that the parameter is a natural-language request that may be routed to different underlying sources, and it gives examples that illustrate acceptable phrasing. This exceeds the baseline 3, though it does not add much beyond what the schema already says.

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

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

The description states a specific verb and resource: 'ask Pipeworx' routes authoritative questions to 5,596 tools across 1,465 verified sources and returns structured answers with stable citation URIs. It explicitly delimits its domain (SEC filings, FDA data, FRED/BLS statistics, patents, weather, clinical trials, news, stocks, crypto, sports, etc.), distinguishing it from generic web search and from the sibling tools that perform narrower jobs.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and enumerates both trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete example queries. It explicitly says to start here for most factual questions, identifies a condition where another tool is better (multi-part/broad questions should go to deep_research), and signals that ask_pipeworx_grounded is a fallback when a broader search is needed.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: candidate routing improvements may be active live, the last candidate was retired on 2026-07-26, it currently matches ask_pipeworx exactly, and it is a full working router with no fallback.

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 front-loads the main identity, then gives current status, usage, and a caveat. It is slightly dense with parentheticals, but each sentence contributes necessary context about an experimental tool.

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

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

For a universal router with no output schema, the description covers the key gaps by referencing ask_pipeworx's exact behavior and response shape. It does not explicitly explain the final response format on its own, but 'same response shape' is sufficient when combined with knowledge of the stable sibling.

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

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

Schema coverage is 100%, so the schema already documents the required 'question' parameter and its aliases. The description does not add parameter-level semantics beyond saying the tool uses the same arguments as ask_pipeworx, which is sufficient for the baseline.

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

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

The description explicitly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,596 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by explaining it carries candidate routing improvements and is currently identical when no candidate is active.

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 usage guidance: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router to decide merges. It clearly mentions the main alternative but does not explicitly state when-not-to-use or address ask_pipeworx_grounded.

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?

While annotations already note the tool is read-only, idempotent, and non-destructive, the description adds significant behavioral context: it reroutes through many sources, extracts only from tool results, returns an evidence quote and confidence, and refuses instead of guessing, with enumerated refusal reasons. This gives the agent an accurate model of when the tool will refuse.

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

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

The description is compact and front-loaded with the most critical fact first. Every sentence adds a distinct piece of information: mode purpose, operational behavior, return/refusal semantics, use cases, and cost tradeoff. No filler or repetition.

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

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

Even without an output schema, the description details both success and refusal response shapes, lists refusal reasons, explains when to use versus sibling, and clarifies cost implications. For a single required parameter and rich annotations, this is complete enough for reliable selection and invocation.

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

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

Schema coverage is 100%; every parameter is documented as the question or an alias for the question. The description does not need to add much parameter detail, and it does not. Baseline 3 is appropriate since the schema fully carries parameter meaning.

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

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

The description states a specific purpose: a hallucination-resistant answer mode for high-stakes reads that extracts answers using only fetched tool results. It clearly distinguishes itself from ask_pipeworx by adding evidence, confidence, and explicit refusal behavior.

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

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

It explicitly says when to use this tool — when answers will be quoted, cited, or acted on, and in high-stakes domains like financial, legal, or medical. It also gives the alternative: prefer ask_pipeworx for casual lookups because this mode costs an extra call.

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, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. 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. It front-loads the purpose and then provides organized sections for classifiers, fan-out examples, response shapes, resolver contract, etc. While verbose, every sentence adds value for agent decision-making.

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

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

Given the tool's complexity (multiple categories, fan-out, varying response shapes, edge cases), the description is comprehensive. It covers return values (result.market, analysis, evidence), resolver behavior, parent event extraction, news fallback fields, and safety mechanisms. No output schema exists, so the description fully shoulders the burden of explaining outputs.

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 meaning beyond schema: explains market input formats (slug, URL, question text), depth enum (quick vs thorough), and include_raw (summarized vs full payloads). This helps agents understand parameter usage beyond type/enum definitions.

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

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

The description clearly states the verb 'Research' and the resource 'Polymarket bet'. It explains that it pulls Pipeworx data in one call and lists example use cases, distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly says when to use it: for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides classifiers and fan-out examples, offering clear context. While it doesn't explicitly state when not to use it, the guidance is sufficient for an AI agent to decide.

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 critical behaviors beyond annotations: off-calendar fiscal year handling, data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, and citation URIs. Annotations already confirm idempotent, read-only, and non-destructive nature with 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 front-loaded with trigger phrases, then provides efficient, well-structured details per entity type, with every sentence adding value and no fluff.

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

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

With 2 parameters, 100% schema coverage, and no output schema, the description fully compensates by explaining the output format (paired data, sorted results, citation URIs), data sources, and usage context, leaving no gaps for the agent.

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

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

Despite 100% schema coverage, the description adds substantial meaning: it explains that 'company' type expects tickers or CIKs and pulls specific financial data, while 'drug' type expects names and pulls adverse-event counts, FDA approvals, and trial counts, far beyond the schema's simple enum and array descriptions.

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

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

The description starts with actionable trigger phrases like 'Compare X and Y' and explicitly states it performs side-by-side comparisons of 2–5 companies or drugs, clearly distinguishing it from sibling tools like entity_profile.

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

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

It explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and explains when to use the tool (comparison queries) and what it replaces (8–15 sequential lookups), providing excellent usage context.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds no additional behavioral context such as output precision, error handling, or side effects. It is adequate but does not exceed what annotations provide.

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

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

The description is a single concise sentence that directly conveys the tool's purpose. It is front-loaded and contains no extraneous words, efficiently communicating the core functionality.

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

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

Given the lack of an output schema, the description does not specify the return format (e.g., string, object) or precision. However, for a simple conversion tool, the missing details are minor and the description is mostly adequate.

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

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

The input schema provides full descriptions for both parameters (lat and lon), so the description adds no further meaning. With 100% schema coverage, baseline is 3; the description merely restates what the schema already conveys.

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

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

The description clearly states the action ('convert'), the input resource ('decimal lat/lon'), and the output format ('degrees-minutes-seconds strings'). It effectively distinguishes from its sibling tool 'dms_to_decimal' by implication.

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 lacks explicit guidance on when to use this tool versus alternatives. While the naming convention and existence of 'dms_to_decimal' suggest the use case, no direct when-to-use or when-not-to-use instructions are provided.

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

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

Annotations already include readOnlyHint/openWorldHint/idempotentHint/destructiveHint, so the bar is contextual. The description goes far beyond: it reveals auth requirements, parallel decomposition, 5,596-tools routing, the findings packet structure (verbatim evidence + confidence + source + fetched_at + citation_uri), the gaps[] behavior, contradictions[] for standard/thorough, depth/tier behavior, semantic excerpting, and expected latency. It also openly warns that current-news topics may return empty gaps, no invented findings.

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 highly informative, front-loaded with the account-required warning. However, it is long and contains structural tangents (for example, the '5,596 tools' detail, and the "one LLM call" parenthetical briefly stepping out of the main flow). Information density is high but prosody and organization are somewhat tangled for quick parsing by an 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?

There is no output schema, but the description thoroughly explains the return shape (findings packet: verbatim evidence + confidence + source + fetched_at + citation_uri, gaps[], contradictions[]) and the operational complexity. It also closes the major context gaps: what breaks (current news), what costs (thorough is paid), and what integration is needed (auth). It lacks a tiny bit of crispness, but for all practical purposes it is complete.

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

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

Schema coverage for parameters is 100%, so baseline is 3. Description adds real value by explaining depth values behaviorally: quick=3 facets/single hop, standard=3 with gap-recovery hop + contradictions scan, thorough=6 paid with iterative chase. It also clarifies 'question' is natural-language and broad/multi-part is acceptable. Slight overlap with the schema but the behavioral depth detail is genuinely additive and disambiguates the enum choices.

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

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

The description clearly states a specific action—grounded multi-source research across 1,465 structured data sources in one call—and explicitly differentiates it from open-web search and from sibling tools like ask_pipeworx. It gives concrete examples of what the tool is best for, making the purpose immediately obvious.

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 structured-data questions, with examples. It also names alternatives ('For a single lookup use ask_pipeworx instead', and prefer ask_pipeworx for breaking/current news) and explains why. It even covers account-tier constraints: free for 'quick'/'standard'.

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

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

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds the mathematical context of computing a destination point and default units, which enhances transparency 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?

A single, well-structured sentence that states the purpose and key parameters upfront. No extraneous words; every part 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?

While parameters are fully covered and the tool is simple, the description lacks explicit mention of the output format (e.g., returns a lat/lon point). For a geospatial computation, this omission could require inference.

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 each parameter is described. The description adds value by grouping parameter meanings, stating default unit (km), and clarifying bearing orientation (0=N, 90=E), which goes beyond the schema 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 verb 'compute' and the resource 'destination point', with explicit inputs (start lat/lon, bearing, distance). It distinguishes itself from sibling tools like 'distance' which computes distance between two 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?

The description implies usage for finding an endpoint given start, bearing, and distance, but does not explicitly state when to use this tool versus alternatives like 'distance' or when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: returns top-N tools with schemas and curated examples, ready to call directly without a second lookup. No contradictions.

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

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

The description is comprehensive but somewhat long. It front-loads the core purpose and then provides examples and usage guidance. Every sentence adds value, but a slight trim could improve conciseness without losing information.

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

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

Given the tool's role (discovery) and the richness of sibling tools, the description fully equips an agent to decide when and how to use it. It explains what the output contains (schemas, examples) despite no output schema. 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 description coverage is 100%, so description does not need to add much parameter detail. The description mentions 'natural language description' and aliases but does not elaborate on parameter behavior beyond what the schema provides. Meets baseline but adds no extra semantics.

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

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

The description uses specific verbs like 'find' and 'discover' and clearly identifies the resource as 'tools'. It lists many example domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that are more specific.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists when to use (browse, search, look up) and provides examples, leaving no ambiguity about its role relative to other tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. Description adds useful context by naming the haversine formula and detailing the output (multiple distance units and bearing), enhancing transparency.

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

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

Single sentence efficiently communicates purpose and output without extraneous words. Every part is essential.

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?

Description covers input (lat/lon points) and output (distance in multiple units and bearing). With no output schema, the description adequately explains what the tool returns, leaving little 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?

Parameter schema has 100% coverage with descriptions, and the description adds the algorithm name but no additional parameter-specific meaning beyond what the schema provides. Baseline of 3 is appropriate as description adds marginal value.

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

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

Description clearly states it computes great-circle distance and bearing between two lat/lon points, specifying output in multiple units. No sibling tool performs the same function, so it distinguishes well.

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 explicit when-to-use or when-not-to-use guidance is provided. Context implies use for geographic distance calculations, but no alternatives or exclusions 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's addition of accepted input formats and the return of decimal values provides useful context beyond the annotations.

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

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

Two clear sentences, no redundancy, and front-loaded with the core purpose. Every word earns its place.

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

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

For a simple single-parameter tool without output schema, the description adequately covers input formats and output type (decimal degrees). Could add note on return type numeric, but not 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 a description and example. The description adds value by specifying additional accepted forms like '-73.5', complementing the schema's example.

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 verb 'parse' and resource 'DMS coordinate string', clearly stating it converts to decimal degrees. It lists accepted forms, and the sibling decimal_to_dms provides the reverse operation, ensuring distinction.

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 implicitly indicates when to use by listing accepted formats, and the sibling decimal_to_dms exists for the reverse. However, no explicit when-not-to-use or alternative guidance beyond the tool's name.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds depth: parallel fan-out across SEC, XBRL, USPTO, news, GLEIF; returns specific fields; notes that patents soft-fail after May 2025; and explains the output structure (e.g., sorted fundamentals, pipeworx URIs). No contradiction with annotations.

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

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

The description is dense and packed with useful information in a single paragraph. It front-loads examples and priority guidance. However, it could be broken into shorter sentences or bullet points for easier scanning. It earns its place without significant waste.

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

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

Given no output schema, the description thoroughly explains return values: CIK, company name, recent filings (with URIs), fundamentals (sorted), patents, news, LEI. It also covers limitations (patents sunset) and edge cases. For a complex tool, this is comprehensive and leaves minimal 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?

Schema coverage is 100% with both parameters described. The description adds value by reinforcing that only ticker or CIK are supported (names not) and that type is currently limited to 'company'. The enum for type is explained with future plans. Slight deduction because the schema already does most of the work.

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 concrete examples ('Tell me about X', 'brief me on Tesla') and a clear verb+resource structure: 'full cross-source profile of a US public company'. It explicitly distinguishes itself from siblings like resolve_entity and compare_entities, stating ALWAYS PREFER over chaining individual lookups.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and warns 'names not supported (use resolve_entity first)'. It also clarifies that only ticker or CIK values are accepted, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the purpose and that it 'clears sensitive data', but does not elaborate on idempotency or error behavior, which is acceptable given existing 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 concise sentences, front-loaded with the action. No extraneous information.

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

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

For a simple one-parameter destructive tool with annotations, the description covers purpose, usage guidelines, and pairing. No output schema needed.

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

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

Input schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete'. The description mentions 'by key' but adds no additional semantic details beyond the schema.

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

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

The description clearly states the verb 'delete' and the resource 'previously stored memory by key'. It distinguishes from siblings by explicitly pairing with 'remember' and 'recall'.

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

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

Provides explicit conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions sibling tools for pairing, but lacks a clear 'when not to use' statement.

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, which the description does not contradict. The description adds process details (fetches page, extracts info, emits markdown) and output format, going beyond annotations.

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

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

The description is a single paragraph, front-loaded with the core purpose, and every sentence adds value without redundancy. It is concise yet comprehensive.

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 absence of an output schema, the description compensates by describing the output format and the process. The tool has only two parameters and a clear purpose, so completeness is good.

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 adds minimal parameter meaning beyond what the schema provides. It mentions default and max for max_links but this is already implicit. 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 uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), clearly stating the tool's output and use cases. It also implicitly distinguishes from sibling tools, which appear unrelated.

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

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

The description lists practical use cases (client's site, own project, auditing competitor) but does not explicitly state when not to use or suggest alternatives. However, the context is clear enough for 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 disclose readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing return fields and mentioning the include_inactive parameter, 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 deliver all necessary information without redundancy or extraneous content, efficiently front-loading the core purpose.

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

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

For a simple listing tool with one optional parameter and no output schema, the description adequately covers purpose, usage context, and return fields.

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

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

Schema coverage is 100%, so the description does not need to elaborate on parameters. It adds no extra meaning beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the action ('List') and resource ('the caller's active subscriptions'), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use this tool: 'review what you're monitoring before adding more or to find an id to cancel', providing clear context for invocation.

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 (which only indicate false hints), the description discloses rate limiting ('5 per identifier per day'), the claim_token mechanism for later retrieval, that no account is required, that it is free and doesn't count against tool-call quota, and that reports are read daily. This enriches the agent's understanding of side effects and constraints.

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 contributes unique information: purpose, usage boundaries, message guidance, token workflow, rate limits, and quota. It is front-loaded with the core action and then adds necessary context. Could be slightly structured, but the density is warranted.

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 the key workflow: filing returns a claim_token, passing it back retrieves status/changes. It addresses prerequisites (no account needed), constraints (rate limit, quota), and scope (only Pipeworx tools). For a feedback tool, this is exceptionally complete.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by explaining how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising users to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This complements rather than repeats 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and enumerates feedback categories (bug, feature/data_gap, praise). It clearly distinguishes this tool from siblings by emphasizing it is exclusively for Pipeworx tools on this connection, unlike reporting to other MCP servers.

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

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

Provides explicit when-to-use guidance: use when a tool returns wrong data, a desired tool is absent, or for praise. It also gives an exclusion: don't report issues with tools from other MCP servers, and tells users how to verify. This is exemplary usage guidance with both inclusion and exclusion criteria.

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

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

Annotations already cover safety and idempotency. The description adds caching duration, data source (CF analytics-engine), PII absence, and output structure, going well beyond what annotations provide.

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

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

The description is concise (4 sentences) with front-loaded purpose, bullet-pointed use cases, and no redundant information.

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

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

Given the tool's simplicity and annotations, the description is mostly complete, covering purpose, use cases, data source, caching, and privacy. It does not specify output limits, but it's implied as 'top'.

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 the parameter fully. The description adds value by explaining the effect of different windows (hot vs. steady-state), extending beyond schema semantics.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over a window, using specific verbs and distinguishing it from sibling tools by its aggregation focus.

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 listed, providing clear context for when to use the tool. However, no direct alternatives or exclusions 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?

The description discloses many behavioral traits beyond annotations: it only scans top ~200 markets by volume for trending mode, uses Jaccard similarity for semantic anchoring, filters placeholders, and includes a fill check that prices against live CLOB depth. This adds significant context that annotations (readOnlyHint, idempotentHint) do not cover.

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

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

The description is verbose but front-loaded with the main purpose and usage modes. Every sentence adds useful information, though it could be slightly more streamlined. For a complex arbitrage tool, the length is justified.

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

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

Despite no output schema, the description explains the response structure (opportunities array with fields, partition_check object, fill check details) and handles edge cases (skipped_low_similarity, null partition signal for high placeholder fraction). It also references polymarket_fill_risk for custom sizing, making it contextually complete.

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

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

Schema coverage is 100% with parameter descriptions, but the tool description adds substantial value: it explains the difference between modes (event vs topic), provides example slugs and seed questions, and details what happens internally (e.g., walking child markets, partition checks). This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It elaborates on different modes (no args, event, topic) and distinguishes from sibling tools like polymarket_fill_risk by specifying its unique algorithm and use cases.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also explains the benefits of cross-event mode over single-event. However, it lacks explicit 'when not to use' or direct comparisons with all siblings, but the guidance is sufficient for most cases.

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

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

The description provides extensive behavioral context beyond annotations, including caching (1h at KV level), model family details (FRED, GDELT, partition overround with sports-specific alpha), response structure, edge calculation (net of slippage, Kelly fractions), and tradeable-edge knobs. No contradiction with readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false.

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 densely packed but well-structured: clear opening statement, breakdown of model segments, response format, tradeable-edge knobs, and diagnostics. Every sentence adds value, earning its place without unnecessary verbosity.

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 9 parameters, no output schema, and complex logic, the description is thorough. It covers model families, edge calculation, response structure (by_segment, fed_candidates, diagnostics), and caching. The agent has all necessary information 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?

All 9 parameters have 100% schema description coverage. The tool description adds further context, such as explaining slippage_pp (zero fees but bid/ask eats 20-50bp) and min_partition_leg_kelly (why min_kelly doesn't filter partitions). This adds significant value beyond the schema alone.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan'), resource ('Polymarket markets'), and distinguishes from sibling tools like polymarket_arbitrage by focusing on edge detection across multiple model families.

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

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

The description explicitly says it's built for 'what should I bet on today' and helps agents avoid paging hundreds of markets. However, it does not provide explicit when-not-to-use guidance or direct comparisons to siblings like polymarket_arbitrage, though the segment filters imply use cases.

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, open world, and non-destructive; description adds detailed response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, daily closes). No contradiction, though annotation coverage was already strong.

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

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

Description is front-loaded with purpose and key question, then parameters, then response structure. Some details are verbose but each sentence adds value. Well-organized for an AI agent to parse.

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 of tracking edge history, description covers response fields, limitations (TTL, daily closes), and competitive insight (median lifespan as competition clock). No output schema exists, but return values are fully explained. Complete for agent usage.

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

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

Schema describes both parameters with 100% coverage. Description adds specifics: default days=14, max=30, window options and default '1wk'. Provides extra context beyond schema, enhancing parameter understanding.

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

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

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge freshness. Distinguishes from sibling tools like polymarket_edges by focusing on historical trends rather than current values.

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 implies usage when historical persistence is needed (fresh vs. old edges) but does not explicitly contrast with alternatives like polymarket_edges. Context is clear enough for an agent to infer, 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description confirms it's a read-only check against live order book depth, walks the ladder, and returns a verdict. It also warns about risks like partial basket fills leading to unhedged directional positions. 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 comprehensive but not overly verbose given the tool's complexity. It is front-loaded with the purpose and includes necessary technical details. The structure uses clear headings (SINGLE-MARKET, BASKET) to organize mode-specific behavior.

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

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

The tool has no output schema, so the description fully compensates by enumerating return fields for both modes. It covers risks, use cases, and fallbacks (e.g., verdict). Could be improved with an example call, but is essentially complete for a complex tool.

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

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

Schema description coverage is 100%, but the description adds significant context beyond the schema. It explains the interpretation of 'size_usd' for single-market vs basket, and the default behavior for 'side' in basket mode. The description also describes the outputs derived from parameters, enhancing usability.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth. It distinguishes two modes (single-market and basket) and explicitly states the outputs. It also 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 states when to use: before acting on polymarket_arbitrage signals or trades above ~$500. Provides rationale (theoretical overround not capturable on thin books, partial fills create unhedged positions). Also specifies requirement of one of 'market' or 'event' parameter.

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, so description adds value by detailing response fields, safety fields, compatibility warnings, temporal alignment, and why spreads might be meaningless. 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 provides essential information. Front-loaded with purpose. Could be more structured but remains focused and justified.

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

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

No output schema provided, so description compensates by thoroughly explaining response structure, safety fields, compatibility conditions, and counters. Covers all necessary context for a complex tool.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds context like the two-mode usage, list of topic shortcuts, and override behavior, enhancing 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?

Explicitly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' Describes two distinct modes (topic shortcuts and explicit pairing) and clearly distinguishes from sibling tools like polymarket_arbitrage.

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

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

Explains when to use (cross-venue comparison), warns about pre-mapped topics not being tradeable, and describes conditions for compatibility warnings. However, does not explicitly name alternative tools when this tool should not be used.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about scoping to identifier and avoiding re-derivation, but the annotations carry most of the behavioral burden.

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?

Very concise: two sentences, front-loaded with action. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: explains purpose, usage, behavioral context, and relationship to 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 coverage is 100% with a clear description. The tool description adds example use cases (ticker, address) and explains the effect of omitting the key, enhancing the schema.

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

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

The description clearly names the action 'retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. It distinguishes itself from siblings by explicitly mentioning '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 clear usage scenarios like looking up context stored earlier, and mentions omitting key for listing. Does not explicitly state when not to use, but pairs with remember/forget for a complete workflow.

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 supplements annotations (readOnlyHint, idempotentHint, etc.) by specifying return fields (source, citation_uri, payload) and behaviors like mark_read affecting subsequent calls. No contradictions.

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

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

Four concise sentences: purpose, return fields, filtering options, and polling/alternative. Front-loaded with key information, 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?

Even without an output schema, the description covers return fields and key behaviors. Minor gap: interaction between mark_read and unread_only is not clarified, but overall sufficient for an agent.

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

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

Although schema coverage is 100%, the description adds practical meaning: explains filtering by type and since, the effect of mark_read, and implies unread_only filters read status. 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 starts with 'Pull fired events from your subscription feed', clearly stating the verb and resource. It distinguishes from sibling tools like 'list_subscriptions' by detailing filtering, mark_read, and unread_only features.

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

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

It provides context for when to use this tool (e.g., polling, retrieving recent alerts) and mentions an alternative API endpoint for scripts/dashboards. However, it doesn't explicitly state 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?

Discloses fan-out to multiple sources, fallback from GDELT to GNews, and soft-fail for USPTO. No contradiction with annotations which correctly mark it as read-only and idempotent.

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

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

Front-loaded with usage examples, each sentence adds necessary detail. Slightly longer but still concise given the complexity of multiple sources.

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

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

Despite no output schema, description explains return structure (grouped by source, total_changes, citation URIs). Covers all aspects of a multi-source tool comprehensively.

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

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

Schema coverage is 100% but description adds value with relative time shorthand, ticker vs CIK examples, and only company type restriction. Extra context beyond schema baseline.

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

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

Description clearly states it provides a change feed for a company over a time window, listing sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes from sibling entity_profile by specifying when to use each.

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 example queries and directs to use entity_profile for static profile instead. Explains the since parameter with examples and typical monitoring value.

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

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

Description discloses write operation ('Save data'), key-value storage, and persistence details (authenticated persistent, anonymous 24-hour). Annotations confirm readOnlyHint=false, idempotentHint=true, destructiveHint=false; description is consistent and adds 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?

Four targeted sentences; front-loaded with purpose; every sentence adds value (when, how, scope, pairing). No fluff.

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

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

Complete for a simple key-value tool with two string params and no output schema. Covers storage, retrieval pairing, persistence, and scoping. No gaps.

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

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

Schema covers both parameters with descriptions. Description adds naming conventions and scope context (scoped by identifier) that enriches meaning beyond schema. Minor addition justifies above baseline 3.

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

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

Clearly states verb 'Save data' and resource 'data the agent will need later'. Distinguishes from siblings (recall, forget) and specifies scope (conversation or sessions).

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

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

Explicitly tells when to use: when discovering something worth carrying forward. Mentions alternatives (recall, forget) and provides context on scope (scoped by identifier, persistence for authenticated vs anonymous).

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

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

Annotations already show safe read-only behavior, and the description adds rich traits: graceful degradation if GLEIF/OpenFIGI are down, explicit source labeling per identifier, unresolved identifiers explicitly stated under 'unresolved,' and internal cascading across multiple endpoints. This greatly aids expectations.

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

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

The description is dense but every sentence delivers new information; no filler. It could be more front-loaded since the core purpose statement appears a third of the way in, but the initial examples are themselves useful and the length is justified by the tool's complexity.

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

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

With no output schema, the description nevertheless explains return semantics: each identifier is labeled with its source, unresolved identifiers are explicitly included, and enrichment failure behavior is described. This makes the tool's behavior fully predictable for the agent.

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

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

Although schema coverage is 100%, the description adds meaning far beyond field names: it documents accepted formats (ticker, CIK, ISIN, name; brand/generic), explains ISIN-to-LEI resolution for non-US issuers, and describes the RxCUI citation output. This turns terse schema entries into usable semantics.

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

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

The description opens with natural-language query examples then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' The verb 'resolve' and resource scope (company vs drug identifiers) clearly distinguishes it 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 explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing a clear trigger context. It does not explicitly name alternative tools or exclusions, but the examples and 'use first' guidance are strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context: probes each entity with ai_visibility_check, ranks by score, returns specific fields (score, confidence, signal density). No contradictions.

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

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

Three sentences: action, process, use case and return. Each sentence is meaningful and compact. No fluff.

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

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

With no output schema, the description adequately describes the return (ranked list with score/confidence/signal density). It mentions dependence on ai_visibility_check. Could briefly note optional params, but schema covers them fully.

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. The description does not add new parameter meaning beyond what the schema already provides (e.g., ordering of entities). Baseline 3 is appropriate.

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

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

Clearly states it compares AI visibility across multiple entities, ranks by score, and returns the most/least recognized. Differentiates from sibling ai_visibility_check (single entity) and compare_entities (comparison 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?

Gives a concrete use case: competitive AI-marketing audits. Does not explicitly state when not to use, but the purpose is clear enough. No mention of alternatives, but the context implies this is for multi-entity comparison.

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

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

Adds rich behavioral context beyond annotations: fans out across deps.dev and bundlephobia, partial failures degrade gracefully, first bundlephobia measurement can take 5-30s, sources_failed lists timeouts. Aligns with readOnlyHint and idempotentHint.

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 relatively long but every sentence adds value. Front-loaded with purpose and composite nature. Slightly verbose but 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?

Comprehensive handling of composite tool: lists return fields (summary, advisories, links, alternatives), mentions NPM-only, partial failures, and bundlephobia timing. No gaps given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra for parameters (e.g., scoped packages accepted, version defaults to latest) but these are already in schema descriptions.

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

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

Description clearly states it's a composite check for npm packages covering license, advisories, bundle size, and more. Distinguishes from siblings by specifying NPM-only in v1 and referencing other ecosystems under deps.dev:version directly.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes limitations like NPM-only and potential bundlephobia timeouts.

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

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

Beyond the annotations (readOnlyHint, etc.), the description discloses specific technical details: embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and the 200K char cap with truncation and flagging. No contradictions with annotations.

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

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

The description is three sentences, each serving a distinct purpose: functionality, use case, and technical details. It is well-organized and concise with no wasted words.

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

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

Given the tool's complexity (semantic search with offsets and scores), the description covers embeddings, windowing, caps, and pairing with a sibling tool. Although there is no output schema, the return format is described adequately.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing natural-language examples for the query parameter and clarifying the text parameter's maximum length, which goes beyond the schema.

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

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

The description clearly states the verb ('search inside') and the resource ('fetched record'), with specific details about its functionality (semantic search, returning passages with offsets and similarity scores). It distinguishes itself from siblings by mentioning ask_pipeworx_grounded and the benefit of saving 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?

The description explicitly advises when to use it ('when the record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded, providing clear usage context and alternatives.

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

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

Annotations provide some behavioral hints (openWorldHint, idempotentHint), but the description adds significant detail: OAuth requirement, delivery limits (SMS 10/day), webhook auto-disable after 10 failures, and returns a signing secret once. No contradictions with annotations.

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

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

The description is thorough but not overlong. It front-loads the core purpose and then details types and delivery. Every sentence adds value, though some could be slightly tighter.

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

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

Given no output schema, the description covers return value, prerequisites, supported types, delivery channels, and limitations. It omits error cases but is otherwise complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, and the description adds extensive meaning to each parameter: it provides type-specific param structures, examples, and delivery constraints (phone verification, webhook HMAC signing). This goes far beyond the raw schema.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription ID. This clearly distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description provides context on when to use (creating subscriptions for specific types) and details prerequisites (Pipeworx OAuth account). It doesn't explicitly say when not to use, but the context and sibling list enable inference.

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. Description adds context that it returns live example questions with tool shapes, and mentions it's drawn from a live catalog. No contradictions.

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

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

Front-loaded with synonyms and purpose, structured with what it does then usage. Slightly verbose but each 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?

With only one optional parameter and no output schema, the description fully explains the return value and usage. Annotations cover behavioral aspects, making the description complete.

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

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

Schema covers 100% with a description of topic. Description adds list of possible topics and clarifies that omitting gives a cross-category spread, adding meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, and distinguishes it from siblings like ask_pipeworx and discover_tools by positioning it as the onboarding entry point.

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

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

Explicitly says to use first when unsure what Pipeworx can do, provides example phrasings, and explains optional topic parameter. Does not explicitly exclude usage scenarios but context is clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds key traits: ownership enforcement, deactivation vs deletion, and preservation of historical events for recent_alerts. 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?

Two sentences, front-loaded with the core action, no redundant words. 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 single-parameter tool without output schema, the description fully covers the effect, ownership constraint, and data lifecycle. 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 schema covers 100% of parameters, and the description adds context that the id comes from subscribe, which aids understanding. Baseline 3, 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?

The description uses a specific verb 'cancel' and resource 'subscription by id', clearly distinguishing it from siblings like subscribe (create) and list_subscriptions. Ownership enforcement further clarifies the scope.

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

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

The description explicitly states ownership enforcement, guiding users that only own subscriptions can be cancelled. It also explains the deactivation behavior, implying when recent_alerts is relevant. However, it does not explicitly contrast with other tools.

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

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

The description goes beyond annotations by explaining the semantics of each verdict, especially crucial caller-facing caveats: 'could_not_verify means the check did not happen… it is NOT evidence for or against the claim,' and 'unsupported means we looked and cover no source for it.' It also discloses that output includes 'verbatim evidence' and 'reasoning,' which are not evident from annotations alone.

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

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

The description is longer than average but every sentence earns its place: trigger phrases, use-case, routing logic, return values, caller warning, and efficiency statement. It is front-loaded with the most important information and structured with clear signposts (e.g., 'IMPORTANT for callers'), though it could be slightly trimmed without losing critical content.

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

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

Given the tool's complexity and no output schema, the description is remarkably complete: it explains what the tool does, how it routes different claim types, what return values look like (verdicts, values, citations), and the subtle distinction between 'could_not_verify' and 'unsupported.' This is sufficient for an agent to invoke and interpret 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 description coverage is 100%: both parameters ('claim' and 'tolerance_pct') are fully described in the input schema, including examples and defaults. The tool description adds no parameter-specific semantics beyond the schema, only general context like 'exact percent-delta math,' so a 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 function with a specific verb ('verify') and resource ('natural-language claim'), and broadens with trigger phrases. It distinguishes itself from sibling tools by describing the unique dual-path routing (SEC EDGAR/XBRL vs. grounded pipeline) and notes it replaces 4–6 sequential calls, 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further provides context-dependent routing instructions (company-financial claims vs. any other factual claim), giving clear guidance on how the tool will behave in different scenarios.

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