Usgs Water

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by detailing probing actions, model selection, scoring per model, and API key handling. No contradiction with annotations.

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

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

Three sentences, front-loaded with purpose, followed by configuration and use cases. 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 tool with 4 parameters and no output schema, the description covers purpose, configuration, return format (per-model data + combined view), and use cases adequately.

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

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

Schema description coverage is 100%, so baseline is 3. Description reinforces schema by providing examples and clarifying the _apiKey pass-through, but does not add substantial new 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?

Clearly states the verb ('probe'), the resource ('LLMs'), and the outcome ('score visibility 0-100'). Differentiates from sibling tools like 'scan_competitor_ai_presence' by focusing on scoring per model rather than scanning presence.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and configuration details (default model, API key requirement for Anthropic). Lacks explicit when-not-to-use or alternative tool comparisons, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant context: internal routing across 3,689 tools, 867 sources, filling arguments, and returning structured answers with stable citation URIs. This goes beyond annotations without contradicting them.

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

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

Front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Contains useful examples and a list of query types. A bit lengthy but each sentence adds value. No wasted words.

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

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

Given the tool's complexity (accessing many domains), the description covers purpose, use cases, and output format (structured answer with citations). No output schema exists, but the description compensates by mentioning the citation URIs. Could mention limitations (e.g., not for subjective questions) but overall complete.

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

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

Schema covers 100% of parameters with descriptions for each alias. The description adds no additional semantic detail beyond the schema (e.g., format, constraints). Baseline of 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool answers factual questions using structured data from verified sources, with specific examples (SEC filings, FDA, etc.) and distinguishes from web search. It uses a strong verb 'prefer over' and identifies the resource as a router to 3,689 tools.

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

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

Explicitly says 'prefer over web search' for factual queries and lists linguistic triggers ('what is', 'look up', etc.). Provides clear use cases and example queries. Does not directly compare to sibling tools like 'ask_pipeworx_grounded', but the guidance is strong enough to avoid misuse.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the exact response structure, refusal reasons, and the fact that it uses only tool result. 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?

Single dense paragraph front-loads the key differentiator ('Hallucination-resistant answer mode') and every sentence adds value, though slightly verbose with some repetition about routing.

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

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

Given no output schema, the description compensates fully by specifying the return format (answer, evidence, confidence, source, etc.) and all possible refusal reasons. Also explains the process and differentiates from ask_pipeworx.

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

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

Input schema has 6 parameters (all aliases for 'question') with 100% description coverage. The tool description adds no extra meaning about parameters beyond what the schema provides, so 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 the tool is a 'hallucination-resistant answer mode for high-stakes reads', using specific verbs like 'EXTRACTS' and 'returns' while distinguishing it from the sibling 'ask_pipeworx' by emphasizing groundedness and refusal handling.

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 (high-stakes where answers are quoted/cited/acted on, e.g., financial, legal, medical) and when not (casual lookups, prefer ask_pipeworx). Also mentions the extra cost trade-off.

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. The description adds extensive behavioral context: low-confidence resolution short-circuit, closed market handling, wide spread illiquidity note, news fallback retry logic, resolver contract inspection advice, and parent_event extraction. 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 well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, parent event, news fields, safety). It is front-loaded with the core action. Some redundancy could be trimmed, but the structure aids comprehension 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 3 parameters, no output schema, and high complexity, the description covers all necessary aspects: input formats, response shapes (market, analysis, evidence), resolver contract, parent events, news fallback, and safety mechanisms. It leaves no significant gaps for an AI agent to infer.

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

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

Schema coverage is 100%, but the description adds significant value: explains that 'market' can be a slug, URL, or question text; provides examples; clarifies defaults for 'depth' (thorough) and 'include_raw' (false) with tradeoffs. This goes well beyond the schema definitions.

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

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

The description opens with a specific action ("Research a Polymarket bet") and resource ("Pipeworx data"), then explains the process (resolve market, classify, fan-out, return evidence). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by its comprehensive, multi-source approach.

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 also explains when the tool short-circuits (low confidence, closed markets). However, it does not explicitly contrast with sibling tools or state when NOT to use this tool.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral traits: pulls from SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, sorts results, returns 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 front-loaded with key examples and commands. It is a bit lengthy but every sentence adds value. Slightly more concise would be ideal, but it remains clear and well-structured.

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

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

Given the tool's complexity (two entity types, multiple data sources, comparison logic), the description is thorough: specifies entity count limits, data sources, handling of fiscal years, sorted output, and return format including citation URIs. No output schema needed based on description.

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

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

Schema coverage is 100% but the description adds context: explains what each enum value ('company', 'drug') retrieves and gives examples for values (tickers/CIKs, drug names). This enriches the bare 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 performs side-by-side comparison of 2-5 companies or drugs in a single call, with example queries like 'X vs Y'. It distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. It lacks explicit 'when not to use' but the preference statement is strong.

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

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

Discloses that it returns instantaneous values and is keyless, adding context beyond annotations (readOnly, idempotent, nondestructive). 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?

Two sentences: first states purpose, second provides parameter examples. Extremely concise with no wasted words.

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

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

Despite no output schema, description sufficiently explains return behavior (most recent per site × parameter) and parameter usage. Complete for this simple 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 coverage is 100%, but description adds value by explaining parameter_codes with examples and defaults (streamflow and gage height). This clarifies usage beyond the schema.

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

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

Description clearly states it returns latest instantaneous readings for USGS gauge sites, specifies it returns most recent value per site × parameter, and lists common parameter codes. This differentiates it from siblings like daily_values.

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

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

Implicitly suggests use for real-time data via 'instantaneous' and 'most recent', and mentions 'Keyless' indicating no auth needed. However, no explicit when-not-to-use or alternative tool guidance is provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it is 'keyless' (no API key needed) and specifies it returns one statistic per day, providing useful context beyond annotations.

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

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

Four sentences, each adding value. Front-loaded with main purpose, followed by use cases and common codes. No redundant or vague statements.

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 is provided, and the description does not specify the output format (e.g., list of date-value pairs). For a time series tool, this is a notable gap. Other aspects are adequately covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for parameter codes (e.g., 00060 for discharge) and stat codes (e.g., 00003 for mean), which are not in the schema descriptions, enriching 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 specifies the tool returns daily-values time series for a single USGS site and parameter over a date range, with a specific verb ('returns') and resource ('USGS site'). It outlines the output (one statistic per day) and provides common codes. Sibling tools are unrelated, so no confusion.

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 usage for trends, hydrographs, and historical comparison, indicating when to use. However, it does not explicitly state when not to use or provide alternatives, though no similar tools exist among siblings.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, and idempotentHint true. The description adds value by detailing return format (top-N tools with names, descriptions, full schemas with examples) and stating results are ready to call directly.

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 verbose, listing many domains and repeating the return format. It is front-loaded with purpose but could be more succinct. Every sentence adds value, but some redundancy exists.

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

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

Given 6 parameters (mostly aliases) and no output schema, the description adequately explains what the tool returns and how to use it. It does not mention pagination or ordering, but these are minor 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 descriptions for all 6 parameters, including aliases and limit. The description reinforces the purpose of the query parameter but adds no new parameter-specific 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 finds tools by describing data or task, listing specific domains like SEC filings, FDA drugs, etc. It distinguishes itself from sibling tools by being a meta-tool for discovery, not a specific data tool.

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

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

Explicitly advises to call this first when many tools are available and to see the option set. Provides clear context for use, though does not specify when not to use it beyond implying it's for discovery before direct calls.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds that patents via USPTO 'soft-fails until reactivated' due to sunset, a key behavioral trait not in annotations. Could be more explicit about soft-fail behavior.

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

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

Description is dense but front-loaded with usage examples and then details. Efficient for the information conveyed, though somewhat lengthy.

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

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

Given complexity (multi-source, no output schema), description thoroughly covers inputs, outputs, limitations (patents sunset), and preferred use. Complete for a holistic profile 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. Description adds examples and clarifies names not supported, but largely echoes schema. 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?

Description explicitly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call', listing each component. It distinguishes from siblings like resolve_entity which handle name resolution.

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

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

Description says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', and specifies accepted inputs (ticker or CIK) with fallback to resolve_entity for names.

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. Description adds that results are capped and keyless, but does not contradict annotations. Provides some additional context but overall low incremental value.

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

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

Three sentences, front-loaded with purpose, no wasted words. Concisely conveys essential 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?

Adequately covers purpose, real-time nature, capping, and keyless access. Lacks explicit output format, but no output schema exists. Minor gaps for a complete picture, but sufficient for selection.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by mentioning real-time and capping, which relates to 'parameter_code' and 'limit', but does not significantly enhance 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 discovers active USGS gauge sites in a US state with a given parameter, returning their latest reading. It distinguishes from siblings like 'daily_values' and 'current_conditions' by focusing on site discovery.

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

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

Provides context like 'useful for finding which gauges are live' and notes result caps, but no explicit when-to-use vs. alternatives or prerequisites. Implies usage but lacks explicit guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, but does not disclose additional traits like irreversibility or permission requirements beyond what is structured.

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

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

The description is extremely concise, consisting of two sentences that immediately convey the action and usage. No redundant information.

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

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

With no output schema, the description does not explain return values or error handling (e.g., what if key doesn't exist). It is adequate for a simple delete but not fully comprehensive.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete.' The description's mention of 'by key' adds no new semantic value beyond the schema, justifying the baseline score of 3.

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

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

The description explicitly states 'Delete a previously stored memory by key,' providing a clear verb-resource pairing. It distinguishes itself from siblings 'remember' and 'recall' by naming them.

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

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

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear context for tool selection, though it lacks explicit 'when not to use' guidance.

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

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

Annotations provide readOnlyHint=true and idempotentHint=true. The description adds detailed behavior: fetches the page, extracts title/description/links, and emits standard markdown format. No contradiction, and it enriches beyond annotations.

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

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

Three sentences efficiently cover purpose, process, and use cases. No redundant words, front-loaded with the core 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?

Despite no output schema, the description fully specifies the output: a single text blob in standard llms.txt markdown format, ready to deploy. Combined with rich annotations, all needed context 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 coverage is 100% with clear descriptions for both 'url' and 'max_links'. The description repeats the default/max values for max_links, adding no new semantics 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?

The description clearly states the action ('generate'), the resource ('llms.txt file'), and the context ('for any URL'). It distinguishes itself from sibling tools like 'ai_visibility_check' by focusing on file generation rather than visibility checks.

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: indexing a client's site, drafting for own project, or auditing a competitor. While it doesn't state when not to use it, the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return fields and parameter context without contradicting annotations. It does not disclose additional behavioral details.

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

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

Two efficient sentences: first specifies purpose and outputs, second gives usage guidance. No wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context completely.

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

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

Schema coverage is 100% for the single parameter. Description mentions 'active subscriptions' implying default exclusion of inactive, which aligns with schema. No additional semantic value beyond schema.

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

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

The description states 'List the caller's active subscriptions' with specific return fields. It is clear about the resource and action, but does not explicitly differentiate from siblings like subscribe or unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use, but lacks when-not-to or alternatives.

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

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

Discloses rate limits (5 per identifier per day), no quota impact, and that team reads daily. These details go beyond annotations and set accurate expectations.

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

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

Single paragraph with good front-loading. Somewhat dense but all sentences add value; could be slightly more concise but still effective.

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

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

Given no output schema, the description covers all necessary aspects: purpose, usage, parameters, constraints, and behavioral notes. Complete for a feedback 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%, and description adds meaning by clarifying enum values and message constraints (be specific, 2000 chars). Context object purpose is explained.

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 sends feedback to Pipeworx about issues or praise, with specific examples. It distinguishes from sibling tools as a dedicated feedback channel.

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

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

Explicitly explains when to use (bug, feature, data_gap, praise) and what to avoid (pasting user prompts). Provides clear context for each feedback type.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that data is 'self-aggregating signal from CF analytics-engine, no PII, just (pack, tool, count), cached 5min-1h'. This provides additional behavioral context beyond annotations without contradiction.

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

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

The description is a single paragraph with front-loaded core action, followed by bulleted use cases and a closing sentence on data source and caching. Every sentence adds value; 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?

With one optional parameter, rich annotations, and no output schema, the description is complete. It specifies what is returned (top tools, top packs, count), time windows, use cases, data source privacy, and caching. No gaps.

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

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

The schema has 100% coverage for the single parameter 'window' with an enum and description. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It specifies the verb 'Returns', the resource, and the scope. The sibling differentiation is implicit by focusing on trending data, distinct from discovery or search tools.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases with demand). It does not explicitly state when not to use or name alternatives, but the context is clear and helpful.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details: the logic of monotonicity violations, partition checks, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and the response fields. No contradictions with annotations.

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

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

The description is verbose, spanning multiple paragraphs. While it front-loads the requirement, it could be more concise. Some redundancy exists (e.g., repeating the response structure). Adequate for a complex tool, but could be tighter.

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

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

Given the tool's complexity, the description covers purpose, usage, behavior, and parameter details. It partially describes the response structure, listing key fields. Without an output schema, this is reasonable, but a more structured summary would improve completeness.

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

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

The input schema already has 100% coverage for both parameters. The description adds examples of event slugs and topic seeds, explains the modes, and specifies that full Polymarket URLs are accepted for 'event'. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between 'event' (single-event) and 'topic' (cross-event) modes. However, it does not explicitly differentiate from sibling tools like 'polymarket_edges' or 'polymarket_kalshi_spread', so some ambiguity remains.

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

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

The description provides explicit guidance on when to use each parameter: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It explains the rationale for cross-event mode and warns that calling with no args fails.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds details: response structure with diagnostics, caching (1h KV), model families, and edge calculation, providing comprehensive 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 overly verbose (over 500 words) with dense technical details that could be streamlined. Front-loading is good (first sentence states purpose), but overall it sacrifices conciseness for completeness.

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

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

Despite no output schema, the description fully explains response structure (by_segment, diagnostics) and reasons for empty segments. All 9 parameters are covered with edge cases and defaults. 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 coverage is 100%, but the description adds significant value by explaining parameter semantics (e.g., slippage_pp default rationale, min_edge_pp net of slippage, min_partition_leg_kelly usage). Every parameter gets extra context.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It differentiates from siblings like polymarket_arbitrage by focusing on edge-finding.

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

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

The description explains use case (discovering opportunities without paging) and mentions tradeable-edge knobs. It lacks explicit when-not-to-use or alternative comparisons but 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: compatibility_warning conditions, temporal alignment, skipped cross types, and the note that bet shape mismatches make spreads invalid. 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 longer than average but packs essential information: purpose, modes, response structure, safety fields, and caveats. It is front-loaded with the core purpose, then dives into details. Every sentence adds value, though a minor trim could improve conciseness.

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

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

Given the tool's complexity and lack of output schema, the description fully explains return values (leg-by-leg prices, spreads, safety fields). It covers temporal alignment, compatibility warnings, and mismatch counters. The tool is complex, and the description provides sufficient context for correct invocation and interpretation.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining when to use topic vs explicit parameters, listing all topic values, and noting that explicit parameters override topic. This goes beyond basic schema info.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket for the same question, distinguishing two modes (topic shortcuts vs explicit parameters). It is specific about the verb (compute spread) and resource (two prediction markets), and differentiates from siblings like polymarket_arbitrage which focuses on a single venue.

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: when comparing prices across venues for the same outcome. It also explains when not to rely on the spread via compatibility_warning and temporal_alignment fields. It warns that pre-mapped topics often yield warnings, preventing misuse. This is comprehensive.

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

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

Adds context beyond annotations: scoped to user's identifier, effect of omitting key. Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description aligns with and supplements.

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

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

Three sentences: core function, when to use, pairing references. No wasted words, front-loaded with purpose.

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

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

Given no output schema, description explains return behavior (value or list of keys). Mentions scope and pairing. Covers essential aspects for a simple 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 covers 100% of parameters. Description adds meaning beyond schema by explaining behavior when key is omitted (list all). Also provides examples of typical usage.

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 retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes from sibling tools remember and forget.

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

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

Provides explicit when-to-use: 'look up context the agent stored earlier'. Implicitly advises against using when you need to save (use remember) or delete (use forget). Could be more explicit about alternatives 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds value by explaining that mark_read flags events as read, altering future calls, and describes the return payload contents. No contradiction with annotations.

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

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

Three sentences, each serving a distinct purpose: purpose and payload, filtering options, and usage guidance (polling vs HTTP). No redundant or vague statements.

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

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

Despite lacking an output schema, the description thoroughly covers return fields (source, citation_uri, payload), filtering (type, since), mark_read behavior, and alternative access method. All five optional parameters are addressed sufficiently.

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

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

Schema covers 100% of parameters with descriptions. The tool description adds meaning by giving an example for type ('sec_8k'), clarifying mark_read's side-effect, and explaining since as ISO timestamp. For limit and unread_only, the description relies on schema names, which are clear enough.

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 starts with a specific verb-noun pair ('Pull fired events') and names the resource ('subscription feed'). It lists returned fields (source, citation_uri, payload) and filtering options, clearly distinguishing it from siblings like list_subscriptions.

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

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

Explicitly states that polling works and provides an HTTP alternative for scripts/dashboards. However, it does not explicitly contrast with other sibling tools (e.g., ask_pipeworx, list_subscriptions) or mention 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: parallel aggregation from multiple sources, fallback logic, USPTO status, and output structure (changes grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is moderately long but well-organized, starting with example queries and then detailing sources, parameters, and alternatives. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Given the tool's complexity (multiple data sources, fallback, date formats, and no output schema), the description adequately covers the return structure (changes grouped by source, total_changes, citation URIs), the USPTO soft-failure, and explicitly points to entity_profile for static profile needs. It is complete enough for correct selection and invocation.

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

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

Schema description coverage is 100%, but the description adds value by explaining the 'since' parameter accepts both ISO dates and relative shorthand (e.g., '7d', '30d'), and recommends '30d' for monitoring. It also clarifies that only 'company' type is supported and gives examples for 'value'.

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

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

The description clearly states the tool provides a change feed for a company in a time window, with explicit example queries. It distinguishes itself from the sibling tool entity_profile by specifying that this tool is for dynamic changes while entity_profile is for static profiles.

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

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

The description gives concrete usage examples (e.g., 'What's new with X', 'latest on Y') and explicitly tells when to use entity_profile instead. It also explains fallback behavior between GDELT and GNews, and notes the USPTO soft-failure.

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 important context beyond annotations: persistent vs. 24-hour retention based on authentication. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Description is efficient, front-loading purpose, but could be slightly shorter. No superfluous sentences.

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 parameters and no output schema, the description covers necessary context. Could mention idempotency, but annotations already do that.

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%; description adds examples of key conventions (e.g., 'subject_property') but doesn't provide substantial new semantics. 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?

Description clearly states 'save data the agent will need to reuse later' and specifies scope (conversation or sessions). It distinguishes from siblings 'recall' and 'forget' by mentioning pairing.

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

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

Explicitly says 'use when you discover something worth carrying forward' and provides guidance on pairing with recall/forget. 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?

The description goes beyond annotations by detailing the cascading lookup process and the specific return fields per entity type (e.g., ticker, CIK, company name with citation URI for companies; RxCUI, ingredient, brand for drugs). Annotations already indicate read-only and idempotent, but the description adds valuable operational 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 well-structured and front-loaded with examples, and every sentence adds value. It is slightly long due to the detailed breakdown of entity types, but this is justified given the complexity. Could be marginally more concise.

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 there is no output schema, the description fully explains the return format for both entity types, including specific fields and citation URIs. It covers all necessary context for an AI agent to invoke the tool correctly and understand the results.

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

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

Both parameters are fully described in the schema (100% coverage), and the description adds significant extra meaning: for 'type' it lists supported values, for 'value' it explains accepted formats (ticker, CIK, name for companies; brand or generic for drugs) and notes auto-disambiguation and internal cascading.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples like 'What's the ticker for…' and a direct instruction 'Use FIRST whenever you have a name but need an ID.' It distinguishes itself by being the go-to for identifier lookup, which contrasts with sibling tools that may provide profiles or comparisons.

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

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

The description explicitly says when to use it (when you have a name but need an ID) and provides example queries. However, it does not explicitly mention when not to use this tool or suggest alternatives among the sibling tools, though the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so description adds value by detailing the internal call to ai_visibility_check, the ranking process, and output fields (score, confidence, signal density). 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?

Three concise sentences that front-load purpose, followed by mechanism and value example. Every sentence adds essential information 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?

Despite no output schema, the description sufficiently explains input, process, and output format (ranked list with score, confidence, signal density). Parameters are well-described, and the tool's behavior is fully understandable 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?

With 100% schema coverage, baseline is 3. Description adds clarity: 'entities' first entry is subject, 'models' defaults to workers-ai, '_apiKey' needed only if models includes 'anthropic', and 'context' disambiguates names. This exceeds schema-only info.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('compare') and resource ('AI visibility'). It provides concrete examples and distinguishes from sibling tool 'ai_visibility_check' by emphasizing batch 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 explicitly recommends use for competitive AI-marketing audits and explains the process (probes each entity, ranks by score). It implicitly differentiates from the single-entity sibling tool, though lacks explicit 'when not to use' statements.

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 important behavioral information beyond annotations: composite nature, dependency on two external services, partial failure handling, and specific timeout behavior (5-30s for new versions). No contradiction with annotations.

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

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

The description is well-structured and informative, but slightly verbose. Every sentence adds value, but could be tightened. Still, it's front-loaded with the main purpose.

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

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

Despite no output schema, the description thoroughly explains the return structure (summary block fields, per-advisory detail, links, alternative versions) and handles edge cases (partial failures). 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 coverage is 100% with descriptions for both parameters. The description adds valuable context: scoped packages accepted for 'package' and default behavior for 'version' (latest).

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: a composite check for npm packages (license, advisories, bundle size, etc.) in one call. It uses specific verbs and resources ('scan', 'dependency') and provides a concise summary of functionality.

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 this tool ('Use whenever an agent asks...') and distinguishes from alternatives (deps.dev:version direct for other ecosystems). It also mentions limitations (NPM only, potential timeout from bundlephobia).

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., so the bar is lowered. The description adds detailed behavioral context: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char truncation with flag, and returns character offsets for verifiable quotes. 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?

Highly concise: two paragraphs that front-load the core purpose and usage. Every sentence adds value—no redundant or vague statements. The structure naturally separates 'what it does' from 'when/why to use it' and technical details.

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

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

Given the tool has no output schema, the description adequately explains return format (passages with offsets and scores), algorithm details, and pairing with sibling. Slightly missing an explicit statement that output is an array of objects, but the context is sufficient for an agent to infer.

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

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

Schema coverage is 100% with good descriptions. The tool description adds value by providing concrete examples (e.g., 'SEC 10-K body', 'supply-chain risk') and clarifying the 200K char limit for 'text'. This goes beyond the schema, earning a score above baseline 3.

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

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

Clearly states the tool performs 'semantic search INSIDE a fetched record', specifies inputs (text and natural-language query) and outputs (top-N passages with offsets and scores). Distinguishes from siblings by explaining it pairs with ask_pipeworx_grounded and is used when records are too large for the prompt.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Provides rationale (saves context, returns only relevant passages with offsets for verification). Mentions alternative workflow with ask_pipeworx_grounded, giving clear 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 declare destructiveHint=false and readOnlyHint=false, but description adds key behaviors: requires OAuth, explains delivery channels (feed always on, email/SMS optional with caps, webhook with signing and auto-disable after 10 failures). 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?

Front-loaded with main purpose, well-structured with type and delivery details. Slightly lengthy but each sentence adds necessary information. Efficient for the complexity.

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

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

Covers creation behavior, auth requirement, return value, delivery nuances. No output schema, but description explains return of subscription id and webhook secret. Adequately 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%, but description adds detailed explanations for type (with examples per enum value), params (per-type structure), and delivery (constraints like phone verification, SMS cap, webhook signing). Significantly enhances schema 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 clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states required Pipeworx OAuth account and lists supported types with examples. Does not explicitly name alternatives but implies use case: create vs list or remove. Clear context for when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: returns examples drawn from a live catalog, and can be called without arguments for a full spread. However, it could mention that no data is modified or that output is static per call, but the annotations handle the core behavioral traits.

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

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

Every sentence adds value. The description starts with common user questions, then describes output, then usage instructions. It is appropriately sized, front-loaded, and structured for quick reading.

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 parameter, no output schema, rich annotations), the description covers all necessary aspects: purpose, output details, usage scenarios, and integration with sibling tools. It is complete for an agent to decide when 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 documentation covers the parameter fully with a description. The description adds rich context: provides example values (finance, pharma, betting), explains that omitting topic gives a cross-category spread, and ties the parameter to focusing the output. This goes beyond the schema's basic 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 tool is an onboarding entry point for suggesting questions about Pipeworx's capabilities, and returns category-bucketed example questions with exact tool+argument shapes. It clearly distinguishes from siblings like discover_tools and ask_pipeworx by positioning itself as the first tool to use when unfamiliar.

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

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

Provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to pass a topic parameter vs omit it, and lists the meta-tools as alternatives.

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

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

The description adds behavioral context beyond annotations: it explains that the row is deactivated not deleted, and ownership enforcement is specified. Annotations indicate non-destructive and idempotent, but the description clarifies the exact effect.

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

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

Two sentences efficiently convey purpose, constraint, and behavioral side effect. Every word adds value, and key information is front-loaded.

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

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

For a single-parameter tool with no output schema, the description fully covers the action, constraints, and side effects. It is complete and requires no additional clarification.

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 parameter is fully described in the schema. The description adds the important context that the id is 'returned by subscribe', which helps the agent understand valid input sources beyond the schema's basic type description.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription), with explicit ownership constraint ('you can only cancel your own subscriptions'). It distinguishes from siblings like subscribe or list_subscriptions by focusing on 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?

The description specifies when to use the tool (for your own subscriptions) and explains that deactivation preserves historical data, which guides appropriate use. However, it does not explicitly mention when not to use it or name alternatives.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds important behavioral details: uses SEC EDGAR + XBRL, returns specific verdicts, structured form, citation, and delta. No contradictions.

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

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

The description is somewhat lengthy but well-structured with a clear use-case list, examples, and a summary of benefits. It front-loads the key scenarios and is efficient overall.

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 simplicity (1 parameter, no output schema), the description adequately covers the tool's domain, constraints, return values, and behavioral context. No gaps are apparent.

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 with examples of natural-language claims, clarifying the expected format and domain, which goes beyond the schema's description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, specifically for company-financial claims. It distinguishes from sibling tools by highlighting that it replaces 4-6 sequential calls, making its unique value clear.

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 'whenever the agent needs to check whether something a user said is factually correct.' It provides clear context but does not mention when not to use it or alternatives, though the sibling list implies other options.

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