Openweather

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying return data (AQI scale and pollutants) and showing example usage. 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 two sentences plus an example, highly efficient and front-loaded with key information. No extraneous details.

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 low-complexity tool with 3 parameters and no output schema, the description sufficiently covers purpose, return format, and usage. Minor omission: no units for pollutant concentrations, but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds marginal value by showing example values and explaining AQI scale, but does not provide significant additional parameter meaning beyond what the schema offers.

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

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

The description clearly states the tool retrieves current air quality for given coordinates, returning AQI and pollutant concentrations. It uses a specific verb ('Get') and resource ('air quality'), and is distinct from sibling tools like current_weather.

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 an explicit example and mentions optional API key usage. While no direct 'when not to use' is stated, the tool's specificity to air quality makes its purpose clear relative to 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: cost implications (BYO key pays Anthropic directly), output shape (score, confidence, signals, raw_response), and default model selection, which goes beyond annotations.

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

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

Three sentences front-load the core purpose, then cover usage specifics (default model, API key) and use cases. Every sentence contributes meaning without redundancy or clutter.

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

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

No output schema exists, yet the description fully documents return structure (per-model {score, confidence, signals, raw_response} + combined view). Parameter docs plus description cover all behavior needed for selection and invocation.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds contextual value (default model, BYO key requirement) but does not significantly enhance parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for brand/topic knowledge and scores visibility (0-100) per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring with specific output structure.

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

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

The description provides explicit context: default free model, BYO key for Anthropic, and example use cases (AI-marketing audits, brand checks). However, it does not specify when to avoid this tool or compare 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, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds meaningful behavioral context beyond those: it routes across 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This tells the agent what the invocation will actually do and what kind of result to expect. There is no contradiction with the annotations.

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

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

The description is long but heavily front-loaded with the most important usage signal ('PREFER OVER WEB SEARCH'), then efficient coverage of routes, examples, and sibling alternatives. Some repetition exists between the trigger phrase list, examples, and 'START HERE for most questions', but every section earns its place for an agent deciding among many sibling tools.

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

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

No output schema exists, so the description correctly compensates by stating the return form: a structured answer with stable pipeworx:// citation URIs. It also covers the full decision surface: when to use, when not to use, what inputs look like, what sources are covered, and which alternatives to route to. For a tool with this breadth, the description is remarkably complete.

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

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

Schema description coverage is 100% and the single semantic parameter, question, is well described with alias support. The description adds useful illustrative examples and clarifies that the question may be loose natural language because the tool fills arguments itself. However, most parameter-level meaning is already present in the schema, so this dimension is adequately covered but not substantially elevated by the description.

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

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

The description clearly states what the tool does: routes a natural-language factual question to the right data source among 5,798 tools and returns a structured, cited answer. It also distinguishes itself from adjacent siblings like web search, ask_pipeworx_grounded, and deep_research. This gives the agent a precise mental model of the tool's unique role.

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 is explicit about when to prefer this tool: it names 'PREFER OVER WEB SEARCH', gives concrete trigger phrases ('what is', 'look up', 'find', 'get the latest'), provides examples, and says 'START HERE for most questions'. It also gives condition-based alternatives: use ask_pipeworx_grounded for a single specific claim needing verbatim evidence, and deep_research for broad multi-part questions. This is ideal routing guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by explaining the experimental edge, the current absence of an active candidate, the exact match to ask_pipeworx, and the fact that it is a fully functional router rather than a fallback wrapper.

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 core identity of the tool. It includes relevant specifics like tool count, argument equality, response shape, and current candidate status without excessive fluff. The 'falls back to nothing' clarification earns its place by preventing a likely misconception.

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-question router with rich annotations and complete schema coverage, the description is sufficient. It covers current behavior, relationship to the stable sibling, and expected usage. The lack of a definition for the response shape is mitigated by the statement that it matches ask_pipeworx' response shape exactly.

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

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

Schema description coverage is 100%, and the schema already documents the aliases (q, text, input, query, prompt) and the primary 'question' parameter. The description only says 'same arguments' without adding new parameter-level meaning, so the baseline score of 3 applies.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, explicitly stating it is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by highlighting experimental routing improvements, leaving no ambiguity about what the tool does.

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: use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It implies the stable alternative is for normal use, but does not explicitly state 'use ask_pipeworx for stable production use,' so it stops just short of perfect exclusion guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the grounded extraction mechanism, the extra LLM call cost, the exact success return shape, and a comprehensive list of refusal reasons. This gives the agent strong expectations about behavior and failure modes.

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 information-dense but well-organized: purpose, mechanism, return/refusal contract, usage guidance, and cost trade-off all earn their place. No filler or redundancy; the most important scoping information is front-loaded.

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

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

Given the tool's complexity and absence of an output schema, the description fully compensates by specifying both success and refusal response shapes. The agent knows what to expect, when to use it, and how it differs from ask_pipeworx.

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

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

The description does not add parameter-level detail beyond the schema, but the schema already documents the single semantic parameter 'question' and its aliases with 100% coverage. Baseline 3 is appropriate since the schema carries the burden.

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 purpose: a hallucination-resistant answer mode for high-stakes reads. It clearly describes the operation flow (routing, filling arguments, fetching, extracting from tool results only) and distinguishes itself from ask_pipeworx by emphasizing grounded extraction 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?

The description states exactly when to use this tool: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also explicitly tells the agent to prefer ask_pipeworx for casual lookups, giving a clear decision rule relative to a sibling.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds extensive detail: fan-out patterns, resolver contract, safety, dead market handling, resolution-rule risk. No contradiction.

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

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

Long but every sentence adds value. Could be more structured (bullets), but front-loaded with purpose. Justified given tool 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?

Covers many fan-out cases, safety, response shapes, resolution risks. No output schema but describes responses. Complete for an agent to use correctly.

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

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

Schema coverage 100% so baseline 3. Description adds meaning: market can be slug/URL/text, depth enum explained, include_raw effect described. Examples provided.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It accepts a slug, URL, or question text. This distinguishes 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?

Explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' Provides extensive examples. Although no explicit when-not, the context is clear.

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

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

Beyond annotations (readOnly, idempotent), description adds: pulls latest data, handles fiscal year variations, sorts by primary metric, returns citation URIs, and replaces many lookups. 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?

Single paragraph is dense but not verbose. Front-loaded with trigger phrases. Every sentence adds value, though structure could be more bulleted for readability.

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

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

Covers input format, data sources, sorting, output structure, and efficiency benefits. No output schema, so description compensates. Minor gap: no mention of error handling or data freshness limits.

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

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

Schema coverage is 100% (baseline 3). Description adds meaning: clarifies data sources per type, specifies tickers/CIKs for company vs. drug names, and gives examples. Enhances understanding beyond basic 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 specifies verb 'compare' and resources 'companies or drugs' (2-5). Includes concrete trigger phrases and distinguishes from siblings like entity_profile by emphasizing multi-entity comparison.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Implies alternative (single-entity lookup) but does not name a specific sibling tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral detail by listing return fields and showing an example call, providing value beyond the structured annotations.

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

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

The description is a single, efficient sentence plus an example. It is front-loaded with the main action and contains 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 read-only retrieval tool with no output schema, the description sufficiently explains what data is returned and all parameters are well-documented. The example adds completeness, and annotations cover safety.

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 thorough descriptions. The description adds a concrete example demonstrating the two input patterns (city vs lat/lon) and the units enum, providing practical usage context that aids 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?

The description clearly states the tool retrieves current weather for a city or coordinates and lists specific data fields (temperature, feels like, conditions, humidity, wind speed, cloud cover). The example distinguishes it from siblings like forecast.

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 to use for current weather, implies not for forecasts, and shows how to provide city vs coordinates and units. No explicit alternatives named, but sibling 'forecast' exists and the context is clear.

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

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

Annotations already mark the tool read-only, open-world, and idempotent, but the description goes well beyond them: it discloses account/paid-plan requirements, latency ranges, gap recovery behavior ('never invented'), the guarantee that citation URIs are fetchable, semantic excerpting rather than head-truncation, and the contradictions[] array for standard/thorough. No statement contradicts the annotations.

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

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

The description is dense but not bloated: the account requirement and fallback tool are front-loaded, and every clause adds operational context. It slightly repeats depth-tier details already present in the schema, but that redundancy is minor given how much unique behavioral information is packed in.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: findings fields, gaps[], contradictions[], hop field, citation_uri fetchability, and semantic excerpting are all covered. It also addresses prerequisites, latency, and source scope, leaving no significant call-time unknowns.

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

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

Schema description coverage is 100%, and the schema already explains both question and depth in detail, so the baseline is 3. The description adds value by noting that depth:'thorough' requires a paid plan, giving concrete example questions, and clarifying how depth tiers map to hops and latency — enough to push it above baseline.

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

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

The description states a specific action — grounded multi-source research across 1,517 structured data sources — and clearly differentiates itself from open-web search and the ask_pipeworx sibling for single lookups. It names the output artifact (findings packet with evidence, confidence, source, fetched_at, and citations) and explains the decompose-and-route behavior that distinguishes it from simpler lookup tools.

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

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

Explicit guidance is provided: use ask_pipeworx if not signed in, prefer this tool for broad/multi-part structured-data questions, and switch to ask_pipeworx for a single lookup. The depth parameter options (quick/standard/thorough) are mapped to hop count, cost, and behavior, giving an agent clear decision 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?

Adds significant context beyond readOnlyHint and idempotentHint annotations: explains output includes full schemas with curated examples, and results are ready to call directly. 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?

Well-structured, front-loaded with purpose, then usage and details. Every sentence adds value, though slightly lengthy.

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 discovery tool: covers purpose, when to use, what it returns (including schema examples), and no output schema needed. 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 coverage is 100% and description doesn't add much beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states it finds tools by describing data or task, lists many domains, and distinguishes itself from sibling domain-specific tools by being a discovery meta-tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, though doesn't explicitly say when not to use.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing fan-out behavior, fallbacks (GDELT→GNews), `sources_used`/`sources_failed` semantics, and the expected-empty fda_products case. It tells the agent that an empty section means real 'no data', not a bug, and that private companies return resolved:false with a notes line. No contradiction with annotations; this is model behavior 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?

The description is long, but nearly every sentence earns its place given the tool's multi-source complexity. It is front-loaded with example intents and the preference rule, and structured into sources, return fields, and edge cases. Minor typographical artifacts and slight redundancy around `type`/`value` keep it from being a model of concision.

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

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

With no output schema, the description carries the full burden of explaining return shape, and it succeeds: it enumerates fields (cik, recent_filings with URIs, fundamentals from the latest 10-K, patents, contracts, fda_products, hiring, news, LEI) and explains failure semantics. It even notes expected empty results for certain company types. The only minor omissions are precise formatting/pagination details, which are secondary for an agent deciding to call it.

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

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

Even though the input schema already documents both parameters at 100% coverage, the description adds meaningful semantics: acceptable value shapes (ticker, zero-padded CIK, name), name resolution via SEC EDGAR, interchangeability of `type` values, and private-company behavior. This substantially exceeds the schema's enums and descriptions.

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

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

The description opens with concrete user intents and immediately states the tool's function: a full cross-source profile of a US public company in one parallel call. It explicitly contrasts this with chained single-pack lookups, making the tool's scope and value proposition clear. This is more than a vague verb+resource pairing; it tells the agent exactly what kind of request this satisfies.

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 an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies acceptable inputs and the private-company outcome. However, it does not name sibling alternatives like compare_entities or deep_research or state when NOT to use this tool, so some routing decisions are left to 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=true, idempotentHint=true, destructiveHint=false, which align with the description. The description adds data content details (fields returned) but does not reveal additional behavioral traits such as rate limits, caching, or external API dependencies. It does not contradict annotations.

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

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

The description is two focused sentences plus a concise example. It is front-loaded with the main purpose and data fields. No unnecessary words or repetition.

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

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

The description covers the tool's function, inputs, and output fields. With 6 parameters, no output schema, and full schema coverage, the description provides adequate context. However, it could include a brief note on output format (e.g., JSON structure) to improve completeness, though it remains effective.

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 schema already documents all parameters. The description only adds an example with 'city' and 'count' but no new semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description specifies a unique action ('Get a multi-step weather forecast'), a distinct resource ('3-hour intervals for a city or coordinates'), and lists returned data fields (temperature, conditions, wind speed, precipitation probability). The example and mention of intervals clearly differentiate it from sibling tool 'current_weather'.

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 context (forecast vs. current) is implied but not explicitly stated. There is no 'when to use' or 'when not to use' guidance, nor mention of alternatives like current_weather. The example shows usage but does not clarify when to choose this tool over 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?

The description adds context beyond annotations by indicating the action is for clearing sensitive data and stating it's a deletion. Annotations already declare destructiveHint=true, but the description reinforces the behavioral trait without contradiction.

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

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

Two sentences: one defining the action, one providing usage guidance. No wasted words; front-loaded with purpose and context.

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

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

For a simple deletion tool with strong annotations and full schema coverage, the description is complete. It covers purpose, when to use, and relationships to sibling tools.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly mentioning them.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember' and 'recall', offering clear guidance on alternatives.

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

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

Annotations already declare read-only, non-destructive, idempotent nature. Description adds that it fetches the page, extracts title/description/key links, and outputs markdown format. No contradictions; adds useful process detail.

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

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

Single paragraph, front-loaded with main purpose. Every sentence adds value: describes input, process, output, and use cases. No 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?

Tool is simple with 2 params, no output schema, and no nested objects. Description covers input, process, output format, and appropriate use cases fully. 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 description coverage is 100%, so the schema already documents both parameters well. Description does not add additional meaning beyond what the schema provides, so baseline score of 3 applies.

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

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

Description clearly states the tool generates an llms.txt file for a URL, extracting title/description/key links and outputting markdown. The verb 'generate' with specific resource 'llms.txt file' distinguishes it from siblings which cover unrelated tasks.

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

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

Explicitly lists three use cases: indexing a client site, drafting for own project, auditing competitor. Does not mention when not to use or contrast with siblings, but the context makes it clear this is for llms.txt generation only.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it resolves to lat/lon and provides an example call, which is helpful beyond annotations. 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 two sentences plus an inline example, front-loaded with the purpose, and contains no extraneous words. Every sentence earns its place.

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

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

Given no output schema, the description could mention the exact return format (e.g., lat/lon object), but it says 'geographic coordinates', which is sufficient. It is complete enough for a simple lookup tool with well-documented parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema—it repeats the query parameter but with an example. No additional semantic detail.

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

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

The description clearly states the tool resolves a place name to geographic coordinates, a specific verb+resource. It also distinguishes from siblings by noting its utility before calling air_quality, which requires lat/lon.

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

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

The description provides clear context: 'Useful before calling air_quality' and gives an example. However, it does not explicitly state when not to use or suggest alternatives, though the sibling list includes similar lookup tools like resolve_entity.

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 safety profile (readOnly, idempotent, non-destructive). Description adds return field details and usage context without contradicting annotations.

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

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

Two sentences, no waste. Every sentence adds value: one for output details, one for usage guidance.

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

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

Complete for a simple read-only tool with one optional param and rich annotations. No output schema needed, description covers return and 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 covers the single parameter fully (100%). Description does not add extra semantic details beyond the schema, so baseline score applies.

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 'List the caller's active subscriptions' with specific verb and resource. Returns explicit fields, distinguishing from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No alternative tools mentioned but context is clear.

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

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

Despite minimal annotations, the description discloses the claim_token return mechanism, follow-up usage, rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and human-read cadence ('team reads digests daily'). 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?

Dense but front-loaded single paragraph; the opening sentence states the core purpose, and every subsequent sentence covers a distinct necessary fact (scope, usage, follow-up, limits). 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?

Covers the full workflow: when to file, what to include, how to follow up on an existing report, rate limits, and cost. No output schema, but the token-based response behavior is fully described, so an agent knows what to expect.

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

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

Input schema already describes all 4 params with 100% coverage, so baseline 3. Description adds message guidance ('don't paste the end-user's prompt') and clarifies claim_token usage and exclusivity, earning a 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource+intent. It defines the four feedback types and explicitly distinguishes this tool from other Pipeworx tools, even addressing MCP server boundaries.

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 when a tool returns wrong/stale data... feature/data_gap... praise') and when not to ('if the tool came from a different MCP server... file it with that server instead'). Even includes 'Not sure?' fallback.

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 caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII), adding significant context beyond annotations.

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

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

Concise, front-loaded with main purpose, then structured into use cases and technical details; 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?

Covers purpose, parameters, and use cases well, but lacks explicit output format details (e.g., list structure).

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 parameter, and description adds semantic guidance on window trade-offs (short vs. long term).

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

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

Clearly states it returns trending tools/packs with call volume over a window, distinguishing it from sibling tools like discover_tools or ask_pipeworx.

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 three explicit use cases for when to use, but does not mention when to avoid or compare to alternatives like discover_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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context on Jaccard similarity, partition filter with placeholder fraction, fill check against live CLOB depth, matching annotation traits 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?

Description is dense but front-loaded with purpose. Could be slightly more concise, but the level of detail is appropriate given complexity. Every section adds necessary 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 no output schema, description comprehensively details response structure (opportunities[], partition_check, fill check). Covers all modes, filters, and trade recommendations. Recommends sibling tool for custom sizing.

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

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

Schema has 100% coverage with descriptions. Description adds meaning: event mode recommended for specific market, topic mode searches related events, and explains accepted input formats like URLs. Adds 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?

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes modes (no args, event, topic) and differentiates from siblings like polymarket_fill_risk and polymarket_edges.

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

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

Provides explicit when-to-use for each argument: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Explains cross-event catches patterns single-event misses and mentions fill check and custom sizing with polymarket_fill_risk.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior, all consistent with the description. The description adds significant behavioral details: caching at KV level, internal segments, diagnostics, slippage handling, and edge net calculation. 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 lengthy but well-structured with clear segments and bullet points. It is front-loaded with the main purpose. While every sentence adds value, some redundancy could be trimmed without losing meaning.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally thorough. It explains the three response segments, diagnostics for empty results, caching behavior, and tradeable-edge knobs. It leaves little ambiguity for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds extensive context beyond the schema: detailed explanations for each parameter (e.g., slippage_pp rationale, max_spread_pp and min_liquidity filters, min_partition_leg_kelly use case) that greatly enhance understanding.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx-based edge detection.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides guidance on knobs and filters but does not explicitly mention when not to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds important behavioral details: 60-day snapshot TTL, cache-miss triggers, decay from daily closes not intraday, and response structure. This adds value beyond annotations.

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

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

The description is somewhat long but front-loaded with the core purpose. It explains response structure clearly. Could be broken into sections, but overall efficient for the complexity.

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

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

No output schema, but description fully explains the response: tracked[], expired[], snapshot_dates[], including fields like edge_pp_net, first_seen, trend, decay_pp_per_day, lifespan_days. It also covers data source and limitations, making it 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%, both parameters are described with defaults and constraints. The description adds no new parameter semantics beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It answers specific questions about how long an edge has existed and whether it's shrinking, and distinguishes between fresh and old edges. This differentiates it from siblings like 'polymarket_edges' which likely show current edges without history.

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

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

The description provides clear context for when to use the tool: to answer questions about edge history and stability. It implicitly contrasts with 'polymarket_edges' for current snapshots. No explicit 'when not to use' is given, but the context is sufficient.

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

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

Annotations already declare read-only and idempotent. Description adds rich behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and details risks like thin legs and forced directional risk. No contradiction with annotations.

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

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

Description is well-structured with bold section headers and bullet-like return lists. Though lengthy, every sentence adds value. Minor redundancy (e.g., 'REQUIRES one of...' could be slightly trimmed) but overall efficient for the complexity.

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

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

Despite no output schema, the description fully enumerates return fields for both modes, covers edge cases (thin_legs, forced_directional_risk, max_clean_notional), and provides failure modes (clean|degraded|cannot_fill). Satisfies all contextual needs.

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 4 parameters have schema descriptions (100% coverage). The description adds significant value: explains the dual-mode behavior for market vs event, default side logic for baskets, and clarifies size_usd interpretation (spend vs target proceeds for single-market, settlement notional for basket).

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges, advising use before acting on their signals.

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 requirements: 'REQUIRES one of market or event', provides default behaviors for side and size_usd, and gives clear usage context: use before arb or edge trades above ~$500, warns about partial fills converting arb to directional position.

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

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

Annotations already declare read-only, non-destructive behavior, but the description adds substantial behavioral nuance: both modes run the identical token-overlap matcher, pairing_unverified is set whenever pairs are returned, spreads are gross rather than net of Kalshi fees, unclassified legs are never paired, and null temporal_alignment means 'could not be computed', not 'aligned'. 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 information-dense and front-loaded with the core purpose, but it is very long and reads as a single block of text. There is some redundancy around pairing_unverified and temporal_alignment_unknown, where similar caveats are stated twice. A structured layout with bullets or clearer section breaks would improve scannability without losing 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?

For a tool with no output schema and complex matching behavior, the description is exceptionally complete. It enumerates safety codes, per-leg flags, skipped classification counters, fee treatment, temporal alignment semantics, and the fact that returned pairs may still carry compatibility warnings. An agent has enough detail to call the tool and interpret results safely.

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

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

The input schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining that topic triggers auto-fetching of the matching event on each venue, explicit ticker/slug override the mapped sides, and both modes invoke the same matching logic. This goes beyond simple field 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 defines the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It names the two specific venues, the outcome-matching constraint, and the two operating modes, making it easy to distinguish from single-venue 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 gives clear context for when to use the tool: when the same outcome is priced on both venues and participant-pool divergence creates a potential signal. It explains mode selection (pre-mapped topic vs explicit ticker/slug) and warns that pre-mapped topics are not automatically tradeable. However, it does not explicitly name alternative tools or state when NOT to use this tool.

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

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

Adds context beyond annotations: two modes (retrieve vs. list all), scoping, and pairing. No contradictions. Describes non-destructive, read-only behavior consistently.

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 conveying all essential information without redundancy. Efficiently front-loads 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 simple tool (1 param, no output schema), the description covers purpose, usage, scoping, and pairing. Could mention return format but not necessary.

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 echoes the key usage. Adds context about omitting key to list all, but baseline is adequate.

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

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

Clearly states the verb 'retrieve' and the resource 'value previously saved via remember'. Distinguishes from siblings by pairing with 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 use cases and examples (ticker, address, notes). Mentions scoping to identifier. Though no explicit 'when not to use', the pairing guidance suffices.

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

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

The annotations include readOnlyHint: true, but the description states that setting mark_read:true flags events as read, which is a state mutation. This contradicts the read-only hint. The description also adds value about return structure, but the contradiction forces a low score.

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 extremely concise with four sentences. The first sentence front-loads the core purpose. No extraneous information, every sentence serves a 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 read-only list tool with no output schema, the description effectively explains return fields and behavior. It also mentions an alternative access method and polling suitability, making it sufficiently complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for parameters like type, since, and mark_read (explaining their use). It does not elaborate on limit or unread_only beyond what schema provides, but overall adds 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?

The description clearly states the tool pulls fired events from the user's subscription feed. It specifies what data is returned (source, citation_uri, payload) and filtering options. However, it does not explicitly distinguish from sibling tools like list_subscriptions, though the purpose is distinct.

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 advises that polling works fine and provides an alternative URL for scripts/dashboards. It explains when to use mark_read and the effect on subsequent calls. It lacks an explicit when-not-to-use but the alternatives give indirect 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 readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: it fans out to multiple sources, has a GDELT→GNews fallback, and USPTO soft-fails. No contradiction.

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

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

The description is comprehensive but slightly dense. It front-loads with common query patterns and uses efficient phrasing. Every sentence adds value, though a bit more structure could improve readability.

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

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

Given no output schema, the description adequately explains return structure (changes grouped by source, total_changes count, citation URIs). It addresses the tool's complexity with clear source details and a sibling alternative.

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

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

Schema coverage is 100%, so baseline 3. The description enhances parameter understanding by explaining `since` formats (ISO date or relative, with example '30d'), and that `value` accepts ticker or CIK. This adds 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's purpose: to fetch recent changes for a company (SEC filings, news, patents) within a time window. It uses specific verbs like 'fans out' and distinguishes from the sibling 'entity_profile' 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?

The description provides explicit when-to-use scenarios (e.g., "What's new with X", "latest on Y") and when-not-to-use (use entity_profile for static profile). It also explains fallback behavior and soft-fails.

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

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

Discloses scoping by identifier, persistence differences between authenticated (permanent) and anonymous sessions (24 hours), and idempotent nature. Adds value beyond annotations 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?

Four sentences, front-loaded with purpose. Efficient but slightly wordy in middle sentences; still earns its keep.

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

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

Comprehensive for a write tool: covers storage scope, duration, and pairing with retrieval/deletion. Output schema absent but tool's return is likely success indication; description covers main behavioral aspects.

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 mentions key-value pair but does not add new meaning beyond schema's descriptions.

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

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

Clearly states verb 'save' and resource 'data' (key-value pair) for later reuse. Distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use (discover something worth carrying forward) and pairs with recall for retrieval and forget for deletion, providing clear 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?

While annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds critical behavioral details beyond them: it cascades through multiple endpoints, degrades gracefully when GLEIF or OpenFIGI is unavailable, returns `figi_candidates` for ambiguous matches rather than asserting a single result, and explicitly lists unresolved identifiers under `unresolved`. This goes well beyond the annotations and provides essential insight into how the tool behaves.

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

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

Although lengthy, the description is front-loaded with examples and the core purpose, then systematically covers each supported type, input nuances, and degradation behavior. Every sentence adds necessary information and the logic flows from general usage to specific details, making it well-structured and appropriate for the tool's complexity.

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

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

With no output schema, the description adequately explains what the tool returns: canonical identifiers with source labels, unresolved identifiers listed separately, and `figi_candidates` when ambiguous. It also mentions that it replaces several manual lookups, so an agent has a complete picture of the tool's functionality, including edge cases and failure modes.

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

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

The input schema has basic descriptions for both parameters, but the description substantially enriches them. For `type` it explains the two enum values, and for `value` it details accepted formats per type (ticker, CIK, ISIN, company name for company; brand or generic for drug) and even warns against including trailing security-class words for bonds. This semantic depth far exceeds the schema and is crucial for correct invocation.

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

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

The description opens with concrete example queries and then precisely states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes between the two supported types (company and drug) and positions the tool as the first step when a name but not an ID is available, which differentiates it from sibling tools like entity_profile and compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a clear directive for when to invoke this tool. It further elaborates on the accepted input formats for each type, notes that it replaces 2-3 manual lookups, and explains the degradation behavior, giving comprehensive guidance on usage conditions and alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds rich behavioral context: probing each entity with ai_visibility_check, ranking by score, and returning score/confidence/signal density per entity. 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 two sentences, front-loaded with the core purpose, and every sentence adds essential information without redundancy.

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

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

Given no output schema, the description adequately describes the output (ranked list with score, confidence, signal density). It also explains the process (probes with ai_visibility_check) and the role of parameters. No gaps remain for an agent 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject' for narrative and that 'context' helps disambiguate common names. This goes beyond what the schema descriptions state.

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 ('Compare AI visibility across multiple entities side-by-side') and clearly states the resource and action. It distinguishes the tool from siblings like ai_visibility_check (single probe) and compare_entities (generic) by focusing on competitive AI presence audits.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example question. It does not explicitly state when not to use or list alternatives, but the context and comparison with sibling tools are implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description goes beyond by detailing partial failure behavior, timing of bundlephobia (5-30s), and the sources_failed field. This adds valuable behavioral context.

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

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

The description is dense with information but well-structured, starting with the core purpose and then adding details. Every sentence serves a purpose without redundancy.

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

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

Despite lacking an output schema, the description fully details the return structure (summary block, per-advisory detail, links, alternatives) and covers edge cases like partial failures and ecosystem limitations. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already describes both parameters adequately. The description adds context about accepting scoped packages and version defaulting to latest, which is already in the schema but reinforces 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?

The description clearly states it's a composite check for npm packages, listing the services used (deps.dev and bundlephobia) and the specific aspects checked (license, advisories, size, etc.). It distinguishes itself from sibling tools by its focused 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?

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes ecosystem limitations (NPM only in v1) and directs users to deps.dev directly for other ecosystems.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds significant technical context: uses BGE-base-en embeddings, cosine similarity over 500-char windows, a 200K char cap with truncation flagging, and character offsets for verification. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, followed by usage guidance, pairing suggestion, and technical details. Every sentence adds unique value; there is no redundancy or filler. It is appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies return values (top-N passages with offsets and similarity scores) and mentions truncation flagging. Combined with the high-quality input schema, it provides a complete mental model for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description enriches this by specifying the max input length for 'text' (200K chars) and providing natural-language examples for 'query' (e.g., 'supply-chain risk'). It also clarifies the 'limit' parameter by referencing 'top-N passages'.

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 'semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes from sibling tools like 'ask_pipeworx_grounded' by explaining the pairing pattern. The verb+resource combination is specific and unambiguous.

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

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

The description clearly advises when to use: 'when the record is too big to cram into the prompt'. It explains the benefit (saves context, returns only relevant passages) and suggests an alternative pairing with 'ask_pipeworx_grounded'. This provides explicit selection 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 indicate a non-read-only, non-destructive, idempotent operation. The description adds significant detail: persistence requirement, return of subscription ID, specific type parameters, and delivery channel behaviors (signing, rate limits, auto-disable). No contradiction found.

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

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

The description is front-loaded with the main purpose and uses a structured list of types and delivery options. While dense, every sentence adds value. Slight room for more concise phrasing, but highly efficient for the complexity.

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

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

Given the tool has nested objects, multiple types, and no output schema, the description fully covers prerequisites, type-specific parameters, delivery details, return value, and edge cases (phone verification, webhook signing, auto-disable). 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 coverage is 100%, but the description provides rich examples for each subscription type's 'params' object and explains the 'delivery' object with valid formats and constraints, adding substantial 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 verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and the return value ('new subscription id'). This distinguishes it from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides explicit prerequisites ('Requires a Pipeworx OAuth account'), supported types and delivery channels with constraints (e.g., phone verification, 10/day SMS cap, webhook auto-disable). Could improve by cross-referencing sibling tools, but the guidance is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: it draws from a live catalog of thousands of tools, returns exact tool+argument shapes, and provides topic-bucketed examples. No contradiction with annotations.

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

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

The description is thorough but slightly long. However, it front-loads the purpose and uses examples clearly. Every sentence earns its place, though minor trimming could improve conciseness.

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

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

Given no output schema, the description compensates by describing the output format in detail (category-bucketed example questions with tool+argument shapes). The parameter is fully covered, and the use case as an onboarding tool is completely addressed.

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 one parameter 'topic'. The description significantly adds meaning: it explains the effect of omitting topic (full spread), provides example values, and clarifies the output shape. 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: it returns category-bucketed example questions for onboarding, and distinguishes itself from sibling tools like ask_pipeworx and compare_entities by being the first tool to call when exploring Pipeworx capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or include the 'topic' argument. It could be stronger by stating when not to use this tool, but the context is clear.

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

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

The description adds beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This aligns with annotations (destructiveHint=false, idempotentHint=true) and gives valuable insight into the tool's side effects.

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

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

Two succinct sentences, front-loaded with the action. Every sentence adds value without repetition or unnecessary details.

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 mutation with one parameter, strong annotations, and no output schema, the description provides all necessary context: purpose, ownership constraint, behavioral effect, and connection to related tool (recent_alerts).

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

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

Schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description confirms it's canceled by id but adds no new meaning. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific, and it distinguishes from siblings like subscribe and list_subscriptions.

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

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

It provides clear context with 'Ownership is enforced — you can only cancel your own subscriptions.' It also mentions historical events stay available via recent_alerts, implying when to use that alternative. However, no explicit 'when not to use' or list of alternative tools.

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

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

Annotations already provide readOnly/openWorld/idempotent/non-destructive hints, but the description adds crucial behavioral disclosure beyond those: the meaning of each verdict, especially 'could_not_verify' (check did not happen, carries verification_error, must not be shown as evidence) and 'unsupported' (no source found). It also explains the two routing paths, giving the agent a complete mental model of internal behavior.

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

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

The description is long but every sentence earns its place. It opens with familiar query phrases, states the purpose, covers routing, output semantics, error meanings, and a high-level efficiency note—all without repetition or fluff. The structure flows naturally from usage to behavior to return values.

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 compensates fully by enumerating the verdict values, the actual value + citation format, and reasoning output. It also explains the two internal paths and the failure semantics, so the agent knows exactly what to expect. Given only 2 simple parameters and 100% schema coverage, this is complete.

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

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

Schema coverage is 100%, but the description adds significant value beyond the schema: it explains that tolerance_pct overrides the claim's implied tolerance, suggests 1–2 for hallucination detection, and notes the default is implied by wording capped at 5. The claim parameter also gets real-world examples showing format, which the schema lacks.

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

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

The description specifies a clear verb-resource pairing ('validate claim') and immediately lists natural-language triggers. It explicitly distinguishes the tool's scope from siblings by describing the company-financial fast path vs. the grounded fallback, and notes it replaces 4–6 sequential calls.

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

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

Explicit guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims (SEC EDGAR + XBRL path) and any other claim (grounded pipeline), and explains how tolerance_pct should be adjusted for hallucination detection. This clearly frames when to use the tool and how to tune it.

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