Osv

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 significant value by detailing return format (per-model score/confidence/signals/raw_response + combined view), external API key handling (passed straight through to Anthropic), and cost implications (BYO key, pay 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?

Two sentences succinctly convey core function, return structure, model options, and use cases. Every word serves a purpose with no redundancy, making it ideal for quick agent 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?

Without an output schema, the description adequately specifies return values and model behavior. It covers required parameters, optional context for disambiguation, and external dependencies, providing a complete picture for agent 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%, providing basic parameter definitions. The tool description enhances understanding by clarifying the default model, optional API key requirement for Anthropic, and that the key is relayed directly. 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 probes LLMs for brand visibility and returns scores. It specifies the default model and optional Anthropic probing, distinguishing its functionality from siblings like 'scan_competitor_ai_presence' through explicit use cases like AI-marketing audits.

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

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

The description provides clear use contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and differentiates free vs. paid model usage. However, it lacks explicit when-not-to-use or direct comparison to sibling tools, leaving some guidance implied.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context about routing to many sources and returning citation URIs, enhancing transparency beyond annotations.

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

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

The description is front-loaded with the key preference instruction and structured with examples. It is slightly lengthy but each sentence earns its place.

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

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

Given the tool's complexity (3,641 tools, 851 sources), the description adequately covers when and how to use it, with examples. No output schema is provided, but the description mentions 'structured answer' which suffices.

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 all parameters documented, including aliases. The description adds example questions and emphasizes natural language input, adding value 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 routes questions to over 3,600 tools from verified sources and returns structured answers with citations. It distinguishes itself from web search and other siblings by specifying its advantage for authoritative data.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' for factual queries and lists specific domains (SEC filings, FDA, etc.) and example questions, providing clear when-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?

Adds rich behavioral detail beyond annotations: hallucination resistance, explicit refusals with reasons, extra LLM call cost. No contradiction with readOnlyHint, openWorldHint, 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?

Efficiently packed with purpose, usage, behavioral details, and return format. Slightly long but every sentence adds value.

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

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

Given 6 parameters (all aliases), no output schema, and annotations present, the description covers purpose, usage, behavioral guarantees, return format, refusal reasons—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 all aliases documented. Description adds that question is natural language and used for routing, providing slight additional context 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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, contrasting it with the sibling ask_pipeworx by noting extra cost and use case.

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

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

Explicitly states when to use (quoted/cited/acted-on answers) and when not to (casual lookups prefer ask_pipeworx), providing clear context and 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: resolution contract, parent_event extractor, news fields, safety mechanisms (low-confidence, closed markets), and wide-spread market handling. 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?

Description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Core purpose is front-loaded. Every sentence adds value, though some 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?

Despite no output schema, the description fully explains response shapes, edge cases, and blocking behaviors. Covers classifiers, fan-outs, resolution confidence, parent events, news fallback, and tradeability. 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%. Description adds meaning beyond schema: explains market input flexibility (slug, URL, question text), depth parameter (quick vs thorough), and include_raw parameter (response size control). Each parameter is well-clarified.

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 researches Polymarket bets by pulling Pipeworx data in one call. It lists specific use cases ('should I bet on X') and distinguishes itself from sibling tools by being a dedicated bet research tool.

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

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

Explicitly states when to use the tool with examples like 'should I bet on X'. Provides extensive fan-out examples per bet category. Does not explicitly state when not to use or alternatives, but context 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, openWorldHint, idempotentHint. The description adds details about data sources (SEC filings, FAERS), handling of off-calendar fiscal years, and citation URIs. Almost full disclosure, though no mention of error handling or rate limits.

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

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

The description is somewhat long but well-structured with examples and key phrases front-loaded. Each sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the complexity (two entity types, no output schema), the description adequately covers return format (paired data + URIs) and sorting behavior. It provides enough context for successful 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%, and the description adds rich meaning: explains enum values for type, provides examples for values, and specifies constraints (2-5 items). The description also clarifies how sorting works per type.

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 comparisons of 2-5 companies or drugs, with specific verbs and resource types. It distinguishes itself from siblings by explaining it replaces multiple sequential lookups.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities, providing a clear usage directive. It also implies the tool is optimized for comparisons and sorted results.

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. The description adds valuable behavioral context: it returns top-N relevant tools with full schemas and examples, ready to call directly. It also suggests it's a first step in a workflow. 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 relatively long but well-structured: purpose first, then usage context, then return details. Every sentence adds value. It could be slightly more concise, but it's not verbose.

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

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

Given the complexity of the tool (meta-tool, 6 parameters, no output schema) the description covers the essentials: what it does, when to use, what returns. It doesn't discuss error handling or rate limits, but annotations cover safety. Overall complete enough for a discovery 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 parameters are already well-documented. The description does not add much beyond the schema except for listing alias examples (q, task, search, description) and providing usage examples in the schema's examples field. 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 verb 'Find tools' and the resource is 'by describing the data or task'. It lists many example domains, making the purpose unmistakable. It distinguishes itself from sibling tools by being a meta-tool for 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?

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available...' This clearly tells the agent when to invoke this tool and implies when not to (e.g., when a specific tool is already known).

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

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

Beyond annotations (readOnly, idempotent), the description discloses that it fans out across multiple sources in parallel, soft-fails for patents due to API sunset, and returns specific data fields with 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 a single dense paragraph that is front-loaded with usage examples and efficiently conveys all necessary information without 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 lacking an output schema, the description thoroughly explains the return structure (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with soft-fail notice, news via GDELT→GNews fallback, LEI). It is complete for a complex multi-source 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 description adds value beyond the schema by explaining that 'type' only supports 'company' (with future plans) and that 'value' can be a ticker or zero-padded CIK, explicitly noting that names are not supported. Schema coverage is 100% but description provides additional 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 explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' using concrete examples like 'Tell me about X'. It distinguishes itself from sibling tools that do single-pack lookups.

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

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

The description clearly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly states that names are not supported, directing to use resolve_entity first.

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 deleting previously stored memories and clearing sensitive data, which aligns with the annotations. It does not contradict them and provides additional behavioral nuance.

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 (two sentences) and front-loaded with the action. Every sentence adds value: first states what it does, second gives usage guidance, third suggests related tools. 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 delete tool with one parameter, good annotations, and no output schema, the description is complete. It covers purpose, usage conditions, and sibling relationships, leaving no ambiguity about when and why to use 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?

The input schema covers the single parameter 'key' with a description 'Memory key to delete'. The description does not add further meaning beyond what the schema provides. With 100% schema coverage, a 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 action ('delete a previously stored memory by key') and the resource ('memory'). It distinguishes itself from sibling tools like 'remember' and 'recall' by explicitly pairing with them, making its purpose distinct.

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

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

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests alternatives by mentioning pairing with 'remember' and 'recall', giving clear 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, openWorldHint, idempotentHint; description adds that it fetches the page, extracts title/description/key links, and emits markdown format. No contradiction. Provides useful behavioral context beyond annotations.

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

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

Description is a single paragraph, efficient and front-loaded with the main purpose. Slightly verbose with 'production-ready' and 'AI crawlers...' but sentences are clear and 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 2 parameters, no output schema, and strong annotations, the description covers the tool's behavior, input constraints, and use cases adequately. Lacks details on error handling or response format 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 description coverage is 100%, so baseline 3. Description does not add significant meaning beyond schema; it mentions 'fetches the page' but that is behavioral, not parameter semantics. The schema already describes URL and max_links adequately.

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 AI crawlers, specifying verb ('generate'), resource ('llms.txt'), and scope ('any URL'). It distinguishes from sibling tools by detailing the exact output format and use cases.

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

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

Explicitly lists when to use the tool (clients, own projects, competitor audit) but lacks explicit 'when not to use' or alternatives. Still provides clear context for appropriate invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by stating 'Keyless' (no authentication required?) and listing the return fields (summary, details, aliases, etc.). 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, no filler. The first sentence gives the purpose and key example, the second lists what is returned. Every part earns its place.

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

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

Given one required parameter, full annotations, and no output schema, the description is complete. It explains what the tool does, what input it takes, and what output to expect. 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 provides a description of the 'id' parameter, but the description adds concrete examples of valid IDs (GHSA-, CVE-, PYSEC-). This helps the agent understand the expected format. Schema coverage is 100%, so baseline is 3; examples raise it to 4.

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

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

The description clearly states the tool retrieves full details for a single vulnerability by its OSV ID, with examples of ID formats. This directly distinguishes it from sibling tools like query_package_vulns or scan_dependency that list or search for vulnerabilities.

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: when you have a known OSV ID and need full details. It doesn't explicitly exclude other use cases like listing, but the focus on 'single vulnerability by its OSV ID' makes it clear. No alternative tool is named, but sibling names provide 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, idempotentHint, and destructiveHint, which cover safety and idempotency. The description adds the return fields and context, but the annotations carry the behavioral burden. No contradiction found.

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

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

The description is two sentences, each serving a distinct purpose: stating the action/returns and providing usage context. It is front-loaded with the primary verb 'List' and no extraneous information.

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

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

Given the simple input schema and no output schema, the description adequately explains what the tool does, what it returns, and when to use it. The parameter is documented in the schema. All essential information 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 a clear description for the only parameter (include_inactive). The description does not repeat parameter details, but the schema already suffices, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing vs. creating or removing.

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 guidance: 'review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it, though it does not mention when not to use it.

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

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

Discloses rate limit (5 per day), that it's free, and that feedback is reviewed daily and influences roadmap. Annotations are all false, so description adds critical 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?

Five sentences that are focused and front-loaded with the main purpose. Every sentence adds unique value with no repetition or 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?

Given the simplicity of the tool and full schema coverage, the description covers purpose, usage guidelines, parameter semantics, and behavioral constraints completely. No output schema is needed 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%, but the description adds significant meaning: it explains the type values in detail, clarifies that context is optional, and instructs how to write the message (focused on tools/packs, not user prompts).

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 the tool's purpose: to send feedback about bugs, features, data gaps, or praise. Excludes other uses and differentiates from sibling tools by being a 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?

Provides explicit conditions for use (bug, feature/data_gap, praise) and instructions on what to include (describe in terms of tools/packs, not end-user prompt). Also mentions it's free and does not count against quota.

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 safety (readOnlyHint, idempotentHint, non-destructive). Description adds that data is self-aggregating from CF analytics, no PII, and caching duration.

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

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

Concise at 4 sentences, front-loaded with purpose, every sentence adds value. 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?

Complete given single optional parameter, no output schema, and strong annotations. Description covers all needed 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 covers 100% of parameters. Description adds value by noting default window (24h) and explaining trade-offs between short and long windows.

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 'the top tools, top packs, and total call volume over a recent window', distinguishing it from sibling tools like ask_pipeworx and discover_tools.

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

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

Three specific use cases are given, explaining when to use this tool (discovering hot data, confirming canonical tool, checking alignment). Window trade-offs are explained, but no explicit when-not-to-use.

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

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

The description discloses detailed behavioral traits beyond annotations: walking child markets, checking date-axis/threshold-axis ordering, computing partition_check, semantic anchor for cross-event pairs, and partition filter with placeholder fraction. Annotations only provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so description adds significant 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 detailed but well-structured, starting with the requirement, then explaining modes, then additional filters and response format. Could be slightly more concise, but every sentence provides value. Front-loads critical information (requirement of one parameter).

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

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

Given the complexity of the tool (two modes, partition checks, similarity filters, output fields), the description is comprehensive. It covers input parameters, behavior in each mode, filtering logic, and response structure (including `opportunities[]` fields). No output schema exists, so description compensates well.

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

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

Schema description coverage is 100%, but the description adds extra meaning: explains modes, gives example slugs for `event` (e.g., 'fed-decision-may-2026') and `topic` (e.g., 'Fed rate decision'), and describes behavior for each. This goes beyond schema to help the agent understand 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 identifies the tool as finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes between single-event (event) and cross-event (topic) modes. It specifies verb+resource+scope and differentiates from siblings by focusing on arbitrage detection.

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

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

Explicitly states the requirement of one of `event` or `topic`, with a warning that no args fail. Recommends `event` for specific markets and `topic` for cross-event scanning, and explains when each mode is useful. Does not provide explicit exclusions 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?

The description adds extensive behavioral context beyond annotations: caching (1h KV), detailed model families (lognormal, GDELT, partition_overround, concentrated_longshot), edge calculations, and diagnostics. Annotations already indicate read-only, idempotent, non-destructive, and description aligns with these.

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 with clear sections (purpose, model families, response top-level, knobs, diagnostics). It is front-loaded with the main purpose. While dense, it remains informative and avoids redundancy.

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

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

Given the complexity (9 params, no output schema, three model families), the description is remarkably complete. It explains response structure, diagnostics, caching, and edge cases like Fed note. It compensates for lack of output schema by describing return fields.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by grouping parameters as 'Tradeable-edge filters' and explaining their role in the model families, providing higher-level context not 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?

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It details three model families, distinguishing the tool from siblings like polymarket_arbitrage by focusing on edge 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?

The description explicitly frames the tool for 'what should I bet on today' and mentions Fed betting surface. However, it does not explicitly exclude alternative tools or provide 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?

Beyond annotations (readOnly, idempotent), the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), explains why spreads may be invalid, and clarifies the tool's behavior in non-obvious cases (e.g., bet shape mismatches). 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 relatively long but well-structured and front-loaded. Every sentence adds value, covering purpose, modes, response, and safety. Minor verbosity in explaining skipped_cross_type details could be trimmed, but overall 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?

Given no output schema, the description thoroughly explains the response structure: leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and counters. It also addresses edge cases (skipped cross-type) and non-tradeable situations, making the tool's behavior fully predictable.

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

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

With 100% schema coverage, the description adds substantial meaning: topic is defined with 10 shortcuts and auto-fetch behavior; explicit parameters override topic; interaction between parameters is explained. The description enriches the schema beyond basic types.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It identifies the tool's core function (comparing prices across venues) and distinguishes two input modes, differentiating it from siblings like polymarket_arbitrage.

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

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

The description explicitly explains when to use the tool (to find spreads) and when spreads are meaningful vs meaningless via compatibility_warning and temporal_alignment fields. It warns that pre-mapped topics often return warnings and encourages explicit tickers for reliable results.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context with 'Keyless' (no API key required) and mentions the return format ('compact vuln summary array'), enhancing transparency beyond annotations.

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

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

The description is extremely concise with three short sentences, front-loading the primary purpose. Every sentence adds value 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?

For a single-parameter tool with no output schema, the description covers purpose, usage context, and return type. It is largely complete, though it could mention error handling or limitations but is sufficient for this simple 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 the description does not add additional meaning to the commit parameter beyond what the schema provides ('A git commit hash'). 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 explicitly states the tool finds vulnerabilities for a specific git commit via OSV.dev. It distinguishes itself by noting it's for pinned commit hashes as opposed to released versions, clearly differentiating it from sibling tools like query_package_vulns.

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

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

The description clearly advises using this tool when you have a pinned commit hash rather than a released version, providing clear context. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint) which already indicate safety and idempotency, the description adds that the tool queries the OSV.dev database, filters by version if provided, and returns a compact summary array with specified 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?

Two concise sentences that front-load the purpose, then specify usage variation and return format. No fluff; every sentence adds necessary information.

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

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

Given the tool's simplicity, strong annotations, and fully described schema, the description is complete: it covers purpose, optional parameter behavior, return structure, and data source. No missing context for effective 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?

The input schema already covers 100% of parameters with descriptions. The tool description reinforces this by explaining the effect of omitting version and providing examples for each parameter, adding value 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 known vulnerabilities for an open-source package via OSV.dev. It distinguishes from siblings by mentioning the database source, but does not explicitly differentiate from similar tools like get_vulnerability.

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 include or omit the version parameter ('Omit version to get every vuln known for the package'), but does not explicitly state when to use this tool versus alternatives such as get_vulnerability or scan_dependency.

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 scoping info ('scoped to your identifier') beyond annotations which already declare readOnlyHint, idempotentHint, and destructiveHint. No contradictions.

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

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

Three sentences, front-loaded with core function, uses, and pairing info. 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?

Comprehensive for a simple retrieval tool with one optional param. Covers retrieval, listing, scoping, and pairing. Could mention return format but not essential.

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 param description. Description reinforces behavior (omit to list) and provides usage examples, adding slight 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?

Description clearly states it retrieves a saved value or lists keys, with specific verb 'Retrieve' and resource 'value saved via remember'. Explicitly 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 clear context for when to use (look up stored context) and how to use (omit key to list). Includes examples but no explicit when-not-to-use 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?

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that data is from a persisted feed, discusses mark_read behavior (flagging events as read), and points to an alternative script-friendly endpoint, all consistent 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 concise at 5 sentences, front-loading the purpose and then detailing features. It is well-structured but could potentially be broken into bullet points for even clearer scanning.

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, it adequately describes return fields (source, citation_uri, payload) and covers filtering, mark_read, and an alternative endpoint. It does not mention pagination beyond the limit parameter, but overall complete for a read-only list 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 enhances understanding with examples ('sec_8k' for type) and clarifies the usage of mark_read and since, adding value beyond the schema descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed and specifies the data returned (source, citation_uri, payload). It distinguishes from sibling tools like list_subscriptions, which list subscriptions themselves, not 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?

It provides guidance on filtering by type and since, and explains the mark_read flag for tracking read status. It also mentions polling suitability and an alternative REST endpoint, but does not explicitly state when not to use or compare with 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, idempotentHint, and non-destructive behavior. The description adds rich behavioral context: fallback from GDELT to GNews, soft-fail for USPTO, parameter formats (ISO dates, relative shorthand), and return structure (grouped changes, total count, citation URIs). 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 dense and front-loaded with examples, but it is a single paragraph. Could benefit from slight structural separation of sources and parameters, but remains efficient and clear.

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

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

Given the complexity (multiple sources, fallback, parameter types) and no output schema, the description covers most aspects: sources, fallback, parameter formats, return structure. Could be slightly more structured, but is adequate for an AI agent.

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

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

Schema coverage is 100%, but the description adds significant value: clarifies 'since' accepts ISO dates and relative shorthand with recommendation, 'type' only supports 'company', and 'value' can be ticker or CIK. This goes beyond the schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company in the last N days/weeks/months, with specific query examples. It distinguishes from sibling tool 'entity_profile' by explaining when to use each.

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

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

Explicit examples of when to use the tool are given, and an alternative ('entity_profile') is mentioned for static profiles. However, it does not explicitly state when NOT to use the tool beyond the 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?

Adds context about key-value scoping, persistence differences for authenticated vs anonymous sessions, and 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?

Five well-structured sentences, front-loaded with purpose, 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?

Covers purpose, usage, behavior, and sibling tools; no output schema needed for this simple storage operation.

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 main description adds minimal new info about parameters beyond schema.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, and distinguishes it from sibling tools recall and forget.

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

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

Explicitly tells when to use (discover something worth carrying forward) and pairs with recall/forget, providing clear 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 adds significant behavioral context beyond annotations (e.g., cascading through multiple lookups, returning citation URIs, auto-disambiguation). Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and the description aligns with 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?

Description is well-structured and front-loaded with example queries. Every sentence adds value, though slightly lengthy. No unnecessary 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 two parameters, no output schema, and strong annotations, the description fully explains behavior, inputs, and outputs for both supported types. An agent can correctly select and invoke this tool without additional info.

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

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

Schema coverage is 100%, but the description adds meaning by explaining valid inputs for each type (e.g., ticker/CIK/name for company, brand/generic for drug) and what will be returned. This enriches the schema.

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

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

Description clearly states the tool resolves names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). It uses a specific verb ('resolve') and resource ('entity'), and distinguishes from sibling tools by positioning it as the first tool to use when needing an ID.

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 FIRST whenever you have a name but need an ID' and provides example queries. While it doesn't list alternatives or when-not-to-use, the context is clear and sufficient 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) indicate safe, repeatable operation. Description adds that it probes each entity, ranks by score, and returns detailed metrics (score, confidence, signal density), going beyond annotations.

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

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

Three focused sentences: purpose, method, example. Front-loaded with verb and resource. 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?

No output schema, but description states return format (ranked list with score, confidence, signal density). Parameters fully described. Could optionally mention pagination or size limits, but adequate for tool 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% (all 4 parameters described). Description adds context: entities array (first is subject), context for disambiguation, models default to workers-ai, _apiKey optional for anthropic. Adds value beyond schema.

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

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

The description clearly states it compares AI visibility across entities via ai_visibility_check, ranks results, and identifies most/least recognized. Example use case reinforces purpose. Distinguishes from sibling 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?

Explicitly notes use for competitive AI-marketing audits and provides an example question. Does not explicitly state when not to use, but the purpose implies it's for multi-entity comparison. No alternative tools named, but context signals make it clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will indicate timeouts. This informs the agent about potential delays and error handling.

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

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

The description is relatively long but information-dense with no filler. It front-loads the core purpose and usage. While effective, it could be structured more clearly with bullet points or shorter sentences for easier parsing.

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 fully explains return fields (summary block with specific fields, per-advisory detail, links, alternative versions) and mentions partial failures. This covers all necessary information 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 has 100% coverage for both parameters. Description adds context: scoped packages (e.g., '@types/node') are accepted for the package parameter, and version defaults to latest when omitted. This adds marginal value beyond schema fields.

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 adding an npm package, covering license, advisories, version history, bundle size, and tree-shaking. It uses specific verb+resource (scan_dependency) and distinguishes from siblings like query_package_vulns which focuses on vulnerabilities alone.

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

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

Explicitly states when to use: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also mentions NPM-only scope in v1 and directs to deps.dev:version for other ecosystems, providing clear alternatives.

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

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

Annotations already indicate the tool is read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and input cap (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?

The description is about 100 words, front-loaded with the core purpose. Every sentence contributes meaning: purpose, use case, pairing, and technical constraints. No redundancy or 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?

For a tool with no output schema, the description adequately covers return values (passages with offsets and similarity scores), constraints (200K cap, truncation flag), and integration hint (pair with ask_pipeworx_grounded). All necessary context is provided.

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 all parameters. The description adds value by providing example queries for the 'query' parameter and restating the max length for 'text'. This helps the agent form natural-language queries effectively.

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 semantic search inside a fetched record. It specifies verb 'search', resource 'record', and adds operational details like returning passages with offsets and similarity scores. Differentiates from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: when the record is too large for the prompt. Mentions pairing with ask_pipeworx_grounded for further processing. Lacks explicit when-not-to-use guidance but provides sufficient context for typical use cases.

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

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

The description adds significant behavioral context beyond annotations. It details authentication requirements (Pipeworx OAuth), type-specific parameter structures, delivery channel constraints (SMS cap of 10/day, phone verification), and the returne of subscription id. 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 well-structured with a clear first sentence stating purpose, followed by details on types and delivery. While informative, it is slightly verbose; however, every sentence adds value. Could be slightly more concise but remains 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?

Given the complexity (3 parameters, nested objects, multiple subscription types with varying params, no output schema), the description is exceptionally complete. It covers all necessary context, including type-specific parameters, delivery options, and limitations (SMS cap).

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

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

Schema coverage is 100%, but the description provides rich meaning for each parameter. For params, it explains structure per type with examples. For delivery, it describes options and constraints. This adds substantial value 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 creates a proactive monitoring subscription to a live-data event stream. It lists supported types (sec_8k, polymarket_edge, fred_series, patent_grant) and delivery channels, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and 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 provides clear context on when to use: creating subscriptions for live data monitoring. It mentions prerequisites (Pipeworx OAuth account) and alternatives for pulling alerts (recent_alerts or GET endpoint). It does not explicitly say when not to use but implies that anonymous/BYO cannot persist subscriptions.

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 critical behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and availability of historical events via recent_alerts. 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?

Two short sentences with no wasted words. First sentence defines action, second adds essential 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?

Covers key aspects: action, parameter, ownership, data handling. Missing return value info, but overall sufficiently complete for a simple cancellation 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 reinforces parameter meaning and adds ownership context, providing value 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 action 'Cancel a subscription by id' and the resource (subscription). Distinguishes itself 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?

Implies usage when needing to cancel own subscription, mentions ownership enforcement. Does not explicitly list alternatives or when not to use, 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 indicate safety traits (readOnly, idempotent, openWorld, non-destructive). Beyond that, the description adds key behavioral details: it returns a verdict, structured form, actual value with citation, and percent delta, and scopes to v1 company-financial claims. 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 moderately long but front-loaded with key phrases and examples. Each sentence serves a purpose, though some redundancy (e.g., listing synonyms) could be trimmed without losing clarity. Overall 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?

Despite lacking an output schema, the description fully explains the return value structure (verdict, structured form, actual value with citation, percent delta). It also states limitations (v1, company-financial claims) and what it replaces, making it contextually complete for an agent to understand and invoke.

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 single parameter 'claim' has 100% schema coverage with a description. The tool description adds extra meaning by providing natural-language examples and clarifying expected phrasing, which helps the agent format the input 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 starts with natural-language examples and explicitly states it's for fact-checking claims against authoritative sources, specifically company-financial claims. It clearly distinguishes from sibling tools by specifying its unique domain and replacement of multiple sequential calls.

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

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

The description provides clear guidance on when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains what it replaces, though it does not explicitly mention when not to use or list alternatives among siblings.

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