Weather Gc Ca

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds that it is keyless and uses official ECCC data, providing context beyond annotations. 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 three sentences, efficiently front-loading the core purpose, then detailing return fields, and providing a concrete example. 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?

Despite no output schema, the description lists key return fields (alert name, type, risk colour, affected area, times, excerpt). It covers the main use case. Missing details like error handling or rate limits, but acceptable for a read-only tool.

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

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

The input schema covers all three parameters with descriptions (100% coverage). The description provides an example but does not add significant semantic meaning beyond what the schema already offers. 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 retrieves active Environment Canada weather alerts across Canada, optionally filtered by location. It specifies the resource (weather alerts), source (Environment Canada), and details returned (e.g., alert name, type, risk colour). This distinguishes it from siblings like 'recent_alerts'.

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 mentions optional filtering by location and gives an example but does not explicitly state when to use this tool versus alternatives like 'recent_alerts' or other weather tools. There is no guidance on when not to use it or prerequisites.

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

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

Adds behavioral details beyond annotations: default model, cost implications, and return format (score, confidence, signals, raw_response). No contradiction with readOnlyHint, openWorldHint, etc.

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

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

Compact single paragraph, front-loaded with main action. Every sentence adds value: purpose, defaults, cost, return format, use cases.

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

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

With 4 parameters, rich annotations, and no output schema, the description fully compensates by detailing return structure. Sibling context is adequately differentiated.

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

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

Schema coverage is 100%, but description adds context: model selection cost, default behavior, and return structure. Provides practical guidance beyond basic parameter descriptions.

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

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

The description clearly states it probes LLMs for brand visibility and scores it, specifying default model and optional Anthropic. This distinguishes it from siblings like ask_pipeworx which are general Q&A.

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 (AI-marketing audits, pre-launch checks) and explains when to provide _apiKey for Anthropic. Could be more explicit about when not to use, but 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 cover readOnly, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond those: it explains the routing mechanism, the scope (5,743 tools / 1,500 sources), automatic argument filling, and the stable citation URIs in the response. It doesn't detail failure modes or latency, but the added behavior is meaningful and consistent 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 opening is strong and front-loaded with purpose and examples, but the description repeats the 'START HERE for most questions — even if web search could also answer it. Examples: ...' block several times verbatim. This duplication adds no information and makes the text bloated, so it fails the 'every sentence earns its place' test.

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 high-complexity router with no output schema, the description tells the agent what to expect (structured answer with pipeworx:// citation URIs), when to use it, and provides diverse examples. It doesn't cover ambiguous-query handling or unsupported domains, but what an agent needs to select and invoke the tool correctly is present.

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%: the schema already documents the single 'question' parameter and its aliases (query, q, prompt, text, input). The description's 'fills arguments' refers to the tool's internal behavior rather than adding meaning to the input schema, so the baseline 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 states a specific action: it routes a natural-language question to the right tool among thousands, fills arguments, and returns a structured answer with citation URIs. It names the resource (authoritative real-world data) and explicitly positions itself as the general-purpose router, differentiating it from specialized siblings like climate_daily or current_observations.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks' followed by concrete trigger phrases and examples. It also says 'START HERE for most questions' and even handles the breaking-news case, making it clear this tool should be selected broadly for factual queries.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: candidate routing improvements may be live, none are active right now, and this is a full working router rather than a fallback. That prevents an agent from assuming degraded behavior or a mere proxy to the stable tool.

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-loads the tool's identity and current state. Details like the 5,743 tools and the retirement date add specificity to the experimental status without bloating the description excessively.

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

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

There is no output schema, but the description references the same response shape as ask_pipeworx and instructs identical usage, giving the agent a concrete reference point. It also covers current candidate status and the absence of fallback behavior, which is enough for an agent to decide whether and how to invoke it.

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

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

Schema coverage is 100%, and every parameter is already documented as an alias for the question. The description only adds that it accepts the same arguments as ask_pipeworx, which does not meaningfully extend the parameter-level meaning provided by the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and a universal router with the same tools, arguments, and response shape. It also distinguishes it from the stable ask_pipeworx by emphasizing the experimental routing edge, so an agent can tell them apart.

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 it exactly like ask_pipeworx when the newest routing is desired and notes that no candidate is currently active, so it matches the stable router now. It does not state formal exclusions such as avoiding it in production, but it provides clear routing context and names the stable alternative.

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

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

Beyond the annotations, the description discloses concrete behavioral traits: refusal reasons, the exact success/refusal response shapes, the grounding constraint to only the tool result, and the extra LLM call cost. This goes well beyond what readOnlyHint, openWorldHint, and idempotentHint already communicate.

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 well-structured and front-loaded with the most important distinction. Every sentence contributes either purpose, usage boundaries, response contract, or cost trade-off; nothing feels redundant or wasted.

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

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

Given the annotations and schema, the description covers the tool's behavior, when to use it, what it returns on success, what refusal reasons look like, and how it compares to the sibling tool. It is complete enough for an agent to select and invoke it correctly without additional context.

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

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

Schema coverage is 100%, and the question parameter is already documented with its accepted aliases. The description does not add parameter-specific semantics, but the schema fully carries that burden, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' and contrasts it with ask_pipeworx, making its distinct role obvious. It states a specific behavior: extract answers using only the tool result content, and explicitly names the sibling it mirrors while differentiating its grounded output.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative, ask_pipeworx, and tells the agent to prefer that for casual lookups, including the cost trade-off of one extra LLM call.

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

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

Annotations are readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds extensive behavioral details: market resolution, classification, fan-out, safety mechanisms (low-confidence short-circuits, closed markets), wide-spread market handling, resolution-rule risk, and parent event extraction. It warns agents to inspect market_match_confidence before trusting analysis. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence adds value, though it could be more concise. Overall, it is organized and informative.

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

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

Given the tool's complexity (many classifiers, fan-outs, response shapes, edge cases), the description is thorough. It covers safety, resolution rules, market-match confidence, parent events, news fields, and illiquid markets. Without an output schema, the description compensates fully, providing all necessary information for correct tool 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 coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter (slug, URL, or question text), the depth parameter (quick vs thorough), and include_raw. It provides examples and context beyond the schema, such as behavior differences, justifying a score above baseline.

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

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

The description clearly states the tool 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' specifying the verb, resource, and scope. It distinguishes itself from specialized sibling tools like polymarket_arbitrage by being a general research tool for any bet.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifier examples and fan-out examples, offering clear context. However, it does not explicitly state when not to use the tool, missing some 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the data is from ECCC, keyless, and official, but does not provide additional behavioral traits beyond what annotations cover. No contradiction exists.

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

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

The description is four sentences long, each serving a distinct purpose: defining the tool, giving station ID examples, citing the source, and characterizing the data. It is front-loaded with the core functionality and contains no redundant or 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?

The description covers the key aspects: data content, required parameters, and station identification. However, it omits the 50-day limit on the date range, which is only present in the schema. Including this constraint in the description would improve completeness. The tool is otherwise well-specified given its simplicity and good annotations.

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

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

Schema coverage is 100%, and the schema descriptions for start_date, end_date, and climate_id are clear. The description reinforces the format of climate_id with examples, but these are already present in the schema's examples array. Thus, the description adds minimal 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 it provides daily climate records (max/min/mean temperature, precipitation, snow) from Environment Canada. It specifies the need for a 7-digit climate identifier and gives concrete examples (e.g., '6158355' for TORONTO CITY). This distinguishes it from siblings like current_observations or active_alerts.

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 using a climate identifier from the 'climate-stations collection' and notes it is 'Keyless, official ECCC data.' While it doesn't explicitly state when not to use this tool or list alternatives, the context is clear for its intended use case of historical daily data.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS, FDA), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). No contradictions.

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

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

The description is dense but well-organized with examples and explicit instructions. While it could be slightly more concise, every sentence adds meaningful information. The front-loading of example queries helps quick understanding.

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 complexity: two entity types, multiple data sources, sorting, and response format. Even without an output schema, it explains what is returned (paired data + citation URIs). No major gaps.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds value by explaining what data is pulled for each entity type (e.g., 'latest 10-K revenue + net income' for companies) and the max/min items, enriching the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 entities (companies or drugs), pulling specific financial or regulatory data. It distinguishes itself from sibling tools like entity_profile (single entity) and search_within (different purpose).

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

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

The description gives explicit guidance to 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. It lacks explicit 'when not to use' instructions but is strong on positive usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds context: data is 'keyless, official ECCC data' and 'real-time', which are useful 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?

Two sentences plus a list of fields. Front-loaded with main purpose and key details. No wasted words.

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

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

Tool is simple with 3 parameters and no output schema. Description covers what is returned, data source, and real-time nature. Sufficient for a read-only data retrieval tool.

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

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

Schema has 100% coverage with descriptions for all parameters. Description adds example values (latitude 43.65, longitude -79.38) but does not provide deeper meaning beyond 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?

Description clearly states 'Latest real-time surface weather observations from Environment Canada stations near a point', specifying verb (returns), resource (surface weather observations), and data source. It lists returned fields, distinguishing it from siblings like active_alerts or climate_daily.

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

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

Usage is implied through examples (latitude/longitude for Toronto) and 'near a point', but no explicit when-to-use or when-not-to-use guidance is given. No alternatives are mentioned.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses the account requirement, paid tier for thorough depth, parallel decomposition across 5,743 tools, output structure with confidence/source/fetched_at/citation, explicit gaps[] with never-invented behavior, contradictions[] for standard/thorough, semantic excerpting, and expected latency. This is extensive and 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 and front-loaded with the account requirement and fallback routing, which is good. However, it is quite long and partially redundant with the schema's depth descriptions, repeating details about 'gap recovery,' 'chases leads,' 'contradictions[]', and the paid thorough tier. It earns its length for the most part, but could be tightened.

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, no output schema, and only 2 parameters, the description is remarkably complete. It covers authentication, fallbacks, scope, method, output format, citation resolvability, failure-mode behavior, contradictions, semantic excerpting, and latency. An agent has nearly everything needed to decide whether and how to invoke this tool.

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

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

Schema description coverage is 100% and the depth enum is already well-documented, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the practical consequence of depth choices (multi-step questions resolving in one call, gap recovery, contradiction scans), latency expectations, and the paid-plan gate for thorough. This helps an agent choose a depth value with fuller 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 performs grounded multi-source research across Pipeworx's 1500 structured data sources, decomposing a question into facets and returning a findings packet. It also distinguishes itself from ask_pipeworx by emphasizing it is not open-web search and is for broad/multi-part questions. This makes the tool's purpose and scope explicit.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, and explicitly says to use ask_pipeworx instead for signed-out users, single lookups, and breaking/current-news topics. Naming alternatives and the conditions that route to them is exactly the clarity an agent needs.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description does not need to repeat safety. It adds value by stating that each result includes full input schemas with curated examples and is ready to call directly without a second lookup. This goes beyond annotations and provides useful behavioral insight.

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 slightly long but well-structured: opens with a clear purpose, then usage guidance, a list of applicable domains, return format, and when to call. Every sentence adds value, though some redundancy (e.g., listing domains could be trimmed). Overall, it is efficient and front-loaded.

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

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

Given that the tool has no output schema, the description compensates by explaining the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' With 6 parameters (1 required) and no enums or nested objects, the description fully covers what an agent needs to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining that the query parameter accepts multiple aliases (query, task, q, search, description) and provides examples like 'analyze housing market trends'. This enriches the semantic understanding beyond the schema's individual descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists a wide range of domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-discovery tool that finds other tools, unlike the specific data-retrieval tools listed as siblings.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and distinguishes it from direct query tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it fans out across multiple sources, soft-fails on USPTO patents, reports sources_used/sources_failed, returns resolved:false with a notes line for private companies, and clarifies that empty sections mean 'no data' rather than a bug. This goes far beyond the annotations and gives the agent a realistic model of what will happen when the tool is invoked.

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 almost every sentence carries distinct information: examples, accepted input forms, source fan-out list, resolved:false behavior, and soft-failure semantics. The front-end immediately conveys the core purpose, and the detailed notes are earned. It could be tightened slightly, but the density of useful guidance justifies most of the length.

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

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

Even without an output schema, the description tells the agent what to expect in the response: cik, company_name, resolved_from/resolved_to, recent_filings with URIs, fundamentals fields, per-source sections, sources_used/sources_failed, and the resolved:false behavior. It also covers edge cases like private companies, absent FDA products, and USPTO API sunset. This is unusually complete for a tool with no output schema and makes successful invocation and result interpretation highly likely.

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 coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema: it clarifies that type='company' and type='ticker' are interchangeable, that value can be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR's company-name match. It also gives examples of valid values ('AAPL', '0000320193', 'Moderna'), which helps an agent construct correct invocations.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It enumerates the source types covered (SEC, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, GLEIF) and provides concrete example queries ('Tell me about X', 'research Acme'). This clearly distinguishes it from narrower lookup tools and sibling tools like compare_entities or resolve_entity.

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

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

The description gives explicit usage context: use when a user asks for a holistic view, and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' It also explains what happens for private companies and empty sections, setting expectations for edge cases. It does not explicitly contrast against sibling tools like compare_entities or deep_research, but the 'holistic view of a single public company' guidance is sufficiently clear for an agent to choose 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?

Annotations already provide destructiveHint=true, so the description does not need to re-emphasize destructiveness. It adds useful context about why to delete, but no additional behavioral detail beyond annotations.

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

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

Two sentences, front-loaded with purpose and followed by usage context. Every sentence adds value with no redundancy.

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

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

For a low-complexity tool with one parameter, full schema coverage, and clear annotations, the description is complete. It covers what, when, and related tools.

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

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

Schema coverage is 100%, so description need not elaborate. The parameter 'key' is already described in the schema as 'Memory key to delete'; description adds no extra meaning.

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

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

The description uses a specific verb ('Delete') and resource ('memory') with a method ('by key'). It clearly distinguishes from sibling tools 'remember' and 'recall'.

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

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

The description explicitly states when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and mentions related tools for context.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds transparency by detailing the fetch-extract-emit process and the output being a single text blob. No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence adds value covering purpose, process, and output. 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?

The description explains the input URL, optional max_links, the process, and output format. It does not cover error handling or prerequisites, but given the tool's simplicity and the presence of good annotations, it is sufficient.

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. The description adds minimal extra meaning, only implicitly referencing max_links via default/max values. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb 'generate', the resource 'URL', and the output format. It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

The description explicitly lists three use cases: client indexing, personal drafting, and competitor auditing. It does not specify when not to use, but the context is clear and distinct from sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns specific fields and only active subscriptions by default. No contradictions.

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

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

Two sentences with no wasted words. Front-loaded with core purpose and return fields, followed by 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?

Given simple parameter and no output schema, description covers return fields and usage context adequately. Could mention pagination or maximum results, but not required for this tool.

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

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

Schema description coverage is 100%, so baseline 3 is appropriate. The description does not add new meaning beyond the schema's 'Include cancelled subscriptions' 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?

Clearly states the tool lists the caller's active subscriptions and specifies return fields. Distinguishes from siblings like subscribe and unsubscribe by mentioning using the returned id for cancellation.

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 guidance on when to use: to review monitoring before adding more subscriptions or to find an id for cancellation. Implicitly connects to sibling tools but does not explicitly state when not to use.

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

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

Annotations are all false/neutral, so the description carries the burden. It discloses behavioral traits not visible elsewhere: claim_token return and retrieval, daily rate limit of 5, not counting against quota, and daily digest review by the team. This goes well beyond annotations and fully informs the agent of side effects and constraints.

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

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

The description is long but dense with value: every sentence covers a distinct facet (purpose, when to use, exclusions, claim_token behavior, rate limit, no quota). It is front-loaded with the core purpose before diving into specifics. Slightly verbose but well-organized; no wasted words.

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

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

The tool has 4 parameters including a nested context object and no output schema, but the description compensates fully. It explains the return value (claim_token), the expected message style, the optional context, and the resolution flow. An agent gets all necessary information to use the tool correctly across its modes.

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

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

Schema coverage is 100%, so the description doesn't need to repeat parameter details. However, it adds meaningful usage context for claim_token by showing the exact call format and noting it should be used alone, which is not in the schema. Minor redundancy with schema descriptions but adds practical invocation knowledge.

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 clear, specific verb and resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It enumerates feedback types (bug, feature, data_gap, praise) which distinguishes it from sibling tools like ask_pipeworx or discover_tools. This is a definitive statement of purpose with no ambiguity.

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

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

The description provides explicit when-to-use guidance: "Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)." It also states a clear exclusion: file with a different server for non-Pipeworx tools, and offers a decision heuristic for uncertainty. This is exemplary usage guidance.

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

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

Adds significant context beyond annotations: data source, no PII, caching behavior. Consistent with readOnlyHint and idempotentHint.

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

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

Concise, front-loaded with purpose, then use cases, then technical details. No wasted words.

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

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

Complete for a single-parameter tool with no output schema. Describes return data and caching behavior adequately.

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

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

Adds meaning beyond schema: explains that shorter windows surface current trends, longer show steady-state demand. Schema coverage is 100%.

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 'Returns the top tools, top packs, and total call volume' with specific verb 'Returns' and resource 'trending data'. It distinguishes from siblings by being the only trending 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 lists three use cases and explains window choices. Lacks explicit 'when not to use', but guidance is clear enough.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds extensive behavioral context: monotonicity checks, partition sum checks, Jaccard similarity anchor, placeholder filter, fill check with realizable vs theoretical edge. No contradictions with annotations.

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

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

Description is well-structured with front-loaded summary and clear sections for each mode, semantic anchor, partition filter, fill check. However, it is somewhat verbose (multiple paragraphs) and could be tightened without losing clarity.

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

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

No output schema, but description explains response structure (opportunities[] with fields) and covers edge cases like skipped_low_similarity, partition filter placeholder fraction, and fill check details. References sibling tool for custom sizing. Complete for a complex tool.

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

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

Schema has 100% coverage with descriptions for both parameters. Description goes far beyond: explains what each mode does, provides example event slug formats, details how cross-event scanning works, and explains the 'trending_scan' default. Adds semantic depth not present in schema.

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

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

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three use modes (default trending_scan, event mode for specific market, topic mode for cross-event scanning) and explicitly separates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly guides when to use each parameter: event for specific market slug, topic for cross-event scanning, no args for trending scan. Includes examples of event slugs and seed questions. Recommends event mode for specific markets. Lacks explicit 'when not to use' or alternatives, but 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?

The description adds extensive behavioral context beyond annotations: details the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), caching behavior (KV-level, 1h TTL), response structure (by_segment with diagnostics), and per-opportunity fields. This fully compensates for the lack of annotations, disclosing all relevant behavioral 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?

The description is verbose (~350 words), packing dense technical details. While it front-loads the purpose, it lacks structured formatting (e.g., bullet points) that would improve scanning. Every sentence adds value, but the length reduces efficiency for an AI agent.

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

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

Given the tool's complexity (9 parameters, no output schema, no nested objects), the description is remarkably complete. It covers return structure, model families, caching, edge calculations, and diagnostics, leaving no obvious gaps. This enables confident tool invocation.

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

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

Schema coverage is 100% with detailed descriptions for all 9 parameters. The description adds some contextual value (e.g., explaining tradeable-edge knobs and their filtering logic), but the baseline is 3 since the schema already covers basics. No significant extra meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for opportunity discovery, but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity.

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

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

The description provides context for when to use ('what should I bet on today'), but lacks explicit guidance on when not to use the tool or when alternatives are preferable. It does not compare with siblings, relying on implicit context.

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

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

The description extensively discloses behavioral traits: it reads from daily snapshots, explains response structure (tracked, expired, snapshot_dates), notes limitations (60-day TTL, decay from daily closes, not intraday). This goes well beyond the annotations which already declare readOnly and idempotent.

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

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

The description is somewhat lengthy but well-structured with clear sections (RESPONSE with subfields). It front-loads the purpose and then provides details. Could be slightly more concise, but overall efficient given the complexity.

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

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

Given the tool's complexity and no output schema, the description is sufficiently complete. It explains the output format, limitations, and key concepts (snapshot TTL, decay computation), ensuring an agent can correctly interpret and use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default values and clamping behavior (days: default 14, max 30; window: default '1wk') and the concept of snapshot families, providing context beyond the schema's basic descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and if it's shrinking. It differentiates itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current state.

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

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

The description implies usage for analyzing edge history vs. current edges, but does not explicitly list alternatives or state when not to use. It gives a clear context for when this tool is appropriate (e.g., distinguishing fresh vs. old wide edges).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral details beyond annotations: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, etc.), and warns about forced_directional_risk. No contradiction; description supplements annotations effectively.

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

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

The description is long but well-structured: summary, required parameters, single-market mode, basket mode. It is front-loaded with purpose. Some redundancy exists (e.g., explaining basket mode twice), but given the complexity (two modes, many return fields), it remains fairly concise. Minor trimming could improve, but overall adequate.

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

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

The tool has no output schema, so the description must explain return values, which it does thoroughly for both modes (e.g., top_of_book, vwap_fill_price, per-leg fill detail, thin_legs, forced_directional_risk). It also explains the rationale behind the tool (avoiding partial fills and unhedged positions). For a complex risk-check tool, the description 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% with each parameter described. The description adds contextual semantics: for size_usd clarifies 'max spend on buys, target proceeds on sells' and for side explains default/auto in basket mode. This adds value beyond the schema descriptions, justifying above baseline 3.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and contrasts with sibling tools by implying it should be used before acting on arbitrage or edge signals. The purpose is specific and well-defined.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills convert arb to unhedged direction). This is excellent context for when to use the 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?

The description goes far beyond the annotations by disclosing the keyword/token-overlap matcher, compatibility codes, skipped-leg counting, gross fee treatment, temporal_alignment null semantics, and the 'pairing_unverified' flag. It is exceptionally transparent about heuristics and limitations, with no contradiction to readOnlyHint/idempotentHint.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes) and front-loaded purpose. Every sentence carries substantive information, though the density makes it heavier than a concise ideal.

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

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

With no output schema, the description fully compensates by explaining response fields, safety fields, each compatibility code, fee disclosures, skipped counters, and the semantics of temporal_alignment. It is complete for a complex comparison tool, leaving no critical gap for the agent to call it 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%, so the baseline is 3. The description adds meaningful semantics by explaining the two modes, that explicit mode pairs kalshi_event_ticker with polymarket_event_slug, and that both modes run the same matcher. This clarifies how the parameters interact beyond the schema descriptions.

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

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

The opening sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from single-venue tools. However, it does not explicitly differentiate among siblings like polymarket_arbitrage, so it stops short of a 5.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug pairings) and emphasizes that pre-mapped topics often return compatibility warnings, advising 'pre-mapped ≠ tradeable.' It provides solid interpretive context, but it never explicitly names alternative tools or states 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: scoping to an identifier (anonymous IP, BYO key hash, or account ID), the behavior of omitting the key to list all, and that it avoids re-derivation. 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 three sentences, each efficiently delivering essential information: main action, usage scenario with examples, and pairing with sibling tools. No redundant or filler content.

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

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

Given the tool's simplicity, no output schema, and thorough annotations, the description covers all necessary aspects: purpose, parameter behavior, scoping, and relationships to related tools. It is fully self-contained for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% with the parameter already described as the key to retrieve or omit to list all. The description reinforces this and adds concrete examples of key values (e.g., 'user_research_topic'), which provides additional context beyond the schema's generic 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 explicitly states the verb 'Retrieve' and 'list', identifies the resource ('value previously saved via remember'), and distinguishes itself from sibling tools 'remember' and 'forget' by specifying its reading role. Examples of stored data (ticker, address, notes) clarify the scope.

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

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

The description clearly states when to use the tool ('to look up context the agent stored earlier') and implies when not to (when saving or deleting, use 'remember' or 'forget' instead). It names these alternatives explicitly, providing complete usage guidance.

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

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

Description discloses mutation via mark_read:true, but annotations declare readOnlyHint=true, creating a contradiction. The description is transparent about the behavior, but the contradiction reduces score to 1 per instructions.

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, no fluff. Front-loaded with purpose, then return fields, then filtering/mark_read, then alternative access. Well-structured and efficient.

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

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

Covers return fields, filtering, mark_read behavior, polling, and alternative URL. Lacks mention of limit parameter behavior (default 50) but schema covers that. Adequate for a simple retrieval tool with no output schema.

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

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

Adds meaning beyond schema: gives example for type ('sec_8k'), specifies ISO timestamp for since, explains mark_read effect. Schema already describes parameters, so description adds useful usage context.

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

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

The description states 'Pull fired events from your subscription feed' and lists return fields (source, citation_uri, payload). It distinguishes from siblings like active_alerts by focusing on recent alerts from the feed.

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

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

Clear guidance on filtering by type and since, using mark_read to manage read status, and polling suitability. Also mentions alternative access via URL. No explicit when-not-to-use, but 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?

Discloses multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, soft-fail for USPTO, and return structure (changes grouped by source, total_changes, citation URIs). Annotations already declare readOnlyHint, idempotentHint, etc.; description adds behavioral context 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?

Well-structured with example queries at the start, then source details and parameter explanations. Some redundancy (e.g., both ISO and relative examples) but overall efficient. Slightly long but necessary given complexity.

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

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

Comprehensive: explains multi-source behavior, fallback, soft-fail, return structure, and alternative tool. No output schema, but description covers what to expect. Addresses edge cases (USPTO sunset) and gives usage hints.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining `since` accepts ISO date or relative shorthand with examples ('7d', '30d', '1y'), and `value` can be ticker or CIK. Notes that `type` only supports 'company'. Provides typical usage guidance for `since`.

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

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

Clear verb+resource: provides a change feed for a company. Lists specific queries ('What's new with X', 'latest on Y') and explicitly differentiates from entity_profile for static profiles.

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

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

Explicit when-to-use and when-not-to-use: directs to entity_profile for static profile. Also describes fallback behavior between GDELT and GNews, and soft-fail for USPTO.

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 idempotentHint=true and destructiveHint=false are consistent. The description adds behavioral context: persistence across sessions, scoped by identifier, and 24-hour retention for anonymous sessions. 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 concise (5 sentences) and front-loaded with the main purpose. 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?

The description covers usage, scope, persistence, and pairing with siblings. Despite no output schema, the tool's simplicity and the description's completeness make it fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value with example key names (e.g., 'subject_property', 'target_ticker', 'user_preference'), providing semantic context beyond the generic schema descriptions.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific verb (Save) and resource (data for reuse). It distinguishes from siblings recall and forget, which are explicitly mentioned.

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

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

The description provides explicit guidance on when to use ('when you discover something worth carrying forward') and mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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 traits, and the description adds substantial context beyond them: internal cascading through several lookup endpoints, graceful degradation when GLEIF or OpenFIGI is unavailable (EDGAR identifiers still return), the explicit 'unresolved' field for failures, figi_candidates, and the pipeworx://rxnorm citation format. These behaviors materially shape agent expectations and no contradiction with annotations exists.

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 user intents, but the company-type parenthetical is a sprawling run-on of nested clauses that is hard to parse, and the closing 'replaces 2-3 manual lookups' note is redundant with the prior cascade sentence. Bullet-pointed or broken-out structure would substantially improve agent comprehension of the same content.

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

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

Given the tool's complexity — two entity types, four identifier systems, multiple upstream sources, and no output schema — the description carries the burden of conveying return artifacts and does so well: figi_candidates, the unresolved field, RxCUI + ingredient + brand, and the citation URI are all mentioned. Minor gap: the exact response shape for a successful company resolution is not specified, but coverage is strong for the complexity level.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value over the schema: it documents ISIN as an accepted company input (absent from the schema's value description), explains that FIGI lookup matches instrument names so the issuer must be passed exactly as printed, and specifies drug output (RxCUI + ingredient + brand). This meaningfully enriches what an agent can infer from the schema alone.

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

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

Opens with concrete natural-language query examples that make the tool instantly recognizable, then states a specific verb+resource: resolving user-spoken names to the canonical/official identifiers other tools require as input. The 'Use FIRST whenever you have a name but need an ID' directive and the detailed supported-types breakdown distinguish it from siblings 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?

Explicitly directs 'Use FIRST whenever you have a name but need an ID,' and enumerates accepted input formats (ticker/CIK/ISIN/name; brand/generic drug name) plus a corrective rule: pass the entity name only, never the question's full noun phrase. It provides clear context but does not explicitly name sibling alternatives (entity_profile, compare_entities) and state when to prefer them over 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and idempotent. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a list with score, confidence, and signal density. It does not mention rate limits or auth details beyond the optional _apiKey, but these are covered in parameters.

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

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

The description is three sentences, well-structured, and front-loaded with the main purpose. Each sentence adds value: purpose, operational detail, and usage context. No unnecessary words or redundancy.

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

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

The description covers input constraints (2-8 entities, first is subject) and output format (ranked list with score, confidence, signal density per entity). It does not discuss error conditions or invalid inputs, but with 100% schema coverage and clear annotations, the definition is adequately 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 description coverage is 100%, all parameters have descriptions. The description adds value beyond the schema: it clarifies that the first entity in the array is treated as the 'subject' for narrative, and explains the default for models (workers-ai) and when _apiKey is needed. This extra context helps the agent use the tool correctly.

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 it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. It gives a concrete example ('does Claude know about us as well as our competitors?') and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description says it is 'useful for competitive AI-marketing audits' and provides an example query. It implies that for a single entity, one should use ai_visibility_check, but does not explicitly state when not to use this tool or name alternatives. The context is clear but lacks explicit exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond annotations: it explains the composite fan-out nature, potential 5-30s delay on new versions for bundlephobia, and graceful partial failure handling with sources_failed reporting. 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 slightly verbose but front-loads the core purpose. It lists return fields and constraints in a block, which is informative but could be more structured. Most sentences earn their place, though the return field enumeration could be formatted more concisely.

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

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

Despite no output schema, the description comprehensively lists all return components (summary block, per-advisory detail, links, alternative versions). It covers edge cases like partial failures, timeouts, and ecosystem limitations. This is well-rounded and 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% with both parameters well-described. The description adds context beyond schema: it mentions that scoped packages are accepted for the 'package' parameter and that 'version' defaults to the latest when omitted. This adds meaningful information without redundancy.

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, combining deps.dev and bundlephobia. It specifies the exact purpose: answering questions about safety, popularity, and size. It distinguishes itself from siblings by explicitly limiting to NPM ecosystem and mentioning alternatives for other ecosystems.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only scope and graceful degradation, providing clear context for when to use. It could be improved by explicitly stating when not to use, but the context 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description goes beyond by detailing embeddings (BGE-base-en), chunking (500-char overlapping windows), and limits (200K chars with truncation flag). 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?

Every sentence serves a purpose: core function, use case, examples, pairing, technical details. No filler. Front-loaded with the main action.

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

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

Given no output schema, the description explains return values (top-N passages, offsets, scores), covers limits and pairing, and provides sufficient context for an agent to decide when to use. Complete for the 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 baseline is 3. The description adds value by explaining the role of each parameter: 'text' is already fetched, 'query' is natural language with examples, 'limit' with default. Also reiterates the text cap. Adds meaning beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes itself from siblings like ask_pipeworx_grounded. Verb+resource is explicit: 'search inside a source'.

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

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

Explicitly tells when to use ('when the record is too big to cram into the prompt'), mentions pairing with ask_pipeworx_grounded, and explains the output (passages with offsets) enabling verification. No ambiguity.

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

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

Description adds rich behavioral context (OAuth requirement, delivery channel caps, webhook secret one-time return), but contradicts annotations: idempotentHint=true conflicts with 'create a new subscription' implying non-idempotent creation.

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 with bullet points and examples, but slightly verbose; every sentence adds value, though some examples are duplicated in the schema.

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 most aspects for a complex tool, but lacks output schema and does not describe return structure beyond the subscription id, nor error handling for duplicate subscriptions.

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?

Adds significant value beyond schema with concrete examples for each subscription type, clarifies verification requirements for SMS, and explains type-specific params in detail, despite 100% schema coverage.

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

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

The description clearly states the tool creates a proactive monitoring subscription, specifies the resource and action, and distinguishes by mentioning it returns a new subscription id, which is unique among siblings.

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

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

Provides detailed guidance on when to use each subscription type, required authentication (Pipeworx OAuth account), and delivery channel options. However, it does not explicitly exclude cases where siblings like list_subscriptions or unsubscribe would be more appropriate.

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 behavioral context: returns a live-catalog-based bucket of examples, each with exact tool+argument shape, and explains the function as an onboarding aid.

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

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

The description is detailed but front-loaded with common user queries. Every sentence provides value, though slightly verbose. Structured for quick comprehension.

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

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

Given the tool's simplicity (one optional param, no output schema) and rich annotations, the description fully covers purpose, usage, output nature, and when to invoke. 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% with one optional parameter described. The description enhances the schema by listing allowed values (finance, pharma, etc.) and the effect of omission (cross-category spread), adding meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings by specifying it's for exploring what Pipeworx can do and learning meta-tool 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?

Explicitly instructs to use this tool 'FIRST when you do not yet know what Pipeworx can do' and to 'learn how to call the meta-tools'. Provides alternatives (e.g., meta-tools) and clear usage patterns (no arguments for full spread or topic parameter for focus).

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 behavioral context beyond annotations: ownership enforcement, deactivation vs deletion, and historical availability. Complements annotations which already indicate non-destructive and idempotent.

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

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

Two succinct sentences with no redundancy. Action, constraints, and behavioral nuance are 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?

Fully covers the simple tool's behavior: input, ownership, effect, and result. No output schema needed, and description does not leave 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 provides full parameter description (100% coverage). Description only adds 'returned by subscribe' which is minor and implicit.

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

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

Explicitly states 'Cancel a subscription by id', clearly specifying the action (cancel) and resource (subscription). 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?

Provides clear context: ownership enforcement and that the row is deactivated rather than deleted. Lacks explicit exclusion criteria but gives actionable usage guidance.

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

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

Annotations already assert read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond these: the special meaning of 'could_not_verify' (check did not happen, not evidence), the meaning of 'unsupported', the two verification pipelines, and the exact return contract of verdict/citation/reasoning. There is no contradiction with annotations.

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

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

The description is long but every section adds value: trigger phrases, usage directive, routing logic, return value shape, and critical caller warnings. It is front-loaded with the most important identification information. It could be tightened slightly without losing nuance, but is well organized for a complex tool.

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

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

Given the tool's complexity and the absence of an output schema, the description fully specifies the return contract: the six possible verdicts, the grounded/structured actual value, the pipeworx:// citation, and reasoning. It also clarifies error semantics (could_not_verify with verification_error) and unsupported results, so an agent would know exactly what to expect.

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

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

The input schema already covers both parameters with full descriptions (100% coverage), including claim examples and the tolerance_pct default/cap. The tool description adds little parameter-specific semantics beyond mentioning percent-delta math, so with high schema coverage the baseline score of 3 is appropriate.

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

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

The description opens with recognizable fact-check trigger phrases and explicitly defines the tool as 'natural-language claim verification against authoritative sources,' with a specific outcome (verdicts such as confirmed/refuted). This clearly distinguishes it from general-purpose sibling tools like ask_pipeworx_grounded or deep_research by focusing on judging factual truth rather than answering open-ended questions.

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

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

It explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives internal routing rules for financial vs. non-financial claims. However, it does not name alternative tools or provide explicit 'do not use when' conditions, so it misses the threshold for a 5.

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