Ipaddress

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world. The description adds that probing an LLM scores visibility per model, returns detailed per-model data (score, confidence, signals, raw_response) plus a combined view. It also explains the API key is passed through to Anthropic, which is key 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?

Three sentences: first states purpose, second adds model details and key usage, third summarizes return value and use cases. No waste, perfectly 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?

The description covers what the tool does, how to use it (requiring entity, optional models/key), and what to expect in return (per-model + combined view). Despite no output schema, the description provides enough detail for an agent to understand the output structure. All necessary 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 descriptions for all 4 parameters. The description adds value by explaining the default model, when _apiKey is needed, and that context helps disambiguate common names. This goes beyond the schema to give practical usage guidance.

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 (probe LLMs), the resource (what they know about an entity), and the output (visibility score 0-100). It distinguishes from sibling tools by focusing on AI visibility across models, which is unique among the siblings.

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

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

The description mentions default model (Workers AI) and condition for using Anthropic (requires _apiKey). It lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), providing clear context. However, it does not explicitly exclude when not to use it or contrast 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns structured answers with stable citation URIs and routes to 5008 tools. No contradiction. It adds useful behavioral context beyond annotations, though the annotations already cover safety.

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: front-loaded with priority, then list of data types, explanation, usage guidance, and step-up alternatives. Every sentence adds value, though it could be slightly more concise. Given the complexity of the tool, it's justified.

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

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

Given the tool's high complexity (5008 tools, many sources), the description is exceptionally complete. It covers purpose, usage guidelines, behavioral notes (citations, routing), and examples. No output schema exists, but the description explains the return type 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 coverage is 100%, documenting all parameters with descriptions. The description provides examples but does not add significant semantic meaning beyond the schema. The baseline of 3 is appropriate as the schema already 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 routes questions to a large set of verified sources for authoritative structured data, listing specific data types and example queries. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, earning a top score.

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' and provides conditions for when to use this tool vs. alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). Includes concrete examples and explicit when-not guidance, making it a model for usage clarity.

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 complements annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the experimental nature, source-preference ranking, and that it is a full router. 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 a single paragraph that effectively front-loads the purpose and provides necessary details without unnecessary fluff. Slightly more structured could be beneficial, but it is concise 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 tool's complexity as a router to 5,008 tools, the description covers the key aspects: beta status, same interface, experimental routing, and comparison to stable version. It lacks deep explanation of source-preference ranking specifics but is sufficient for use.

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

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

Schema coverage is 100% with detailed descriptions for each alias. The description adds little beyond confirming it accepts the same arguments as ask_pipeworx, so it meets the baseline but does not enhance understanding further.

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 is a beta version of ask_pipeworx, a universal router with 5,008 tools. It explains the specific improvement (source-preference ranking) and distinguishes itself from sibling tools like ask_pipeworx and ask_pipeworx_grounded by noting that it is identical in arguments and response shape but with experimental routing.

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 it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. It also clarifies that it is a full working router, not a fallback, providing clear context for when to choose this tool over the stable version.

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, etc.), the description explains the underlying process: same routing as ask_pipeworx, picks tool, fetches data, extracts only from tool result. It details return structure and explicit refusal reasons, providing rich 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 a single dense paragraph that front-loads the key purpose. While efficient, it could benefit from slight structural improvements like bullet points for refusal reasons, but it wastes no 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 absence of an output schema, the description fully compensates by detailing the exact return object and potential refusal reasons. It also covers the tool's relationship to siblings and parameter handling, making it highly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that multiple parameter names are aliases for 'question' and describing the question as 'Your question in natural language', which is helpful but not extensive.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb 'ask' and a resource 'Pipeworx Grounded'. It distinguishes itself from the sibling ask_pipeworx by noting extra cost and use case differences.

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 (high-stakes reads where answers will be quoted, cited, or acted on) and when not to use (casual lookups, prefer ask_pipeworx). It also names the alternative tool, fulfilling the when/not/alternatives criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: safety short-circuits for low-confidence matches, dead market handling, wide-spread warnings, resolution-rule risk, and fallback fields. 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 verbose but well-structured, with clear sections: purpose, use cases, classifiers, fan-out examples, response shapes, safety notes. It is front-loaded with the core function. Could be slightly more concise, but every paragraph 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 no output schema, the description thoroughly explains all response fields: market info, analysis with edge calculation, evidence sources, resolver contract, parent event extractor, news fallback, safety statuses, and cancellation rules. Covers all edge cases and provides complete contextual guidance.

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

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

All three parameters have schema descriptions (100% coverage). The description adds substantial meaning: explains the market_input formats (slug, URL, question text), depth options with defaults, and include_raw with usage guidance. Examples further clarify 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 starts with a clear verb+resource ('Research a Polymarket bet') and specifies the use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description explicitly states when to use the tool with three concrete use cases and provides classifier examples. However, it lacks explicit exclusions or comparisons to siblings, slightly reducing clarity.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds valuable context: 'Keyless, offline', which clarifies authentication and network behavior beyond what annotations provide.

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

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

Two short sentences, no unnecessary words. The first sentence immediately states the core functionality, and the second adds critical qualifiers. Perfectly front-loaded and efficient.

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

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

Given the tool's low complexity (single parameter, no output schema, clear computation), the description fully covers what the tool does and what it returns. No missing information.

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 good description for the single parameter. The tool description repeats the example '10.0.0.0/8' but does not add new semantics beyond what is already in the schema. 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 specifies the verb 'Parse' and lists all computed outputs (network address, broadcast, netmask, wildcard, usable host range, host count). It also adds 'Keyless, offline' to clarify the nature of the tool. The name and title are directly aligned.

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 by stating 'Keyless, offline', suggesting it is safe and fast, but it does not provide explicit guidance on when to use this tool versus alternatives like 'parse_ip' or when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and citation URIs—all beyond what annotations provide.

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

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

The description is front-loaded with example queries and key instructions. While slightly verbose, every sentence adds value—no filler. Could be trimmed slightly 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?

With no output schema, the description explains what is returned (paired data, citation URIs). It covers data sources, sorting behavior, and even mentions it replaces 8–15 sequential lookups—leaving no gaps for an agent.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: explains what data each type pulls, gives examples of valid values, and clarifies constraints (max 5 items, ticker vs. drug names).

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 concrete natural-language triggers like 'Compare X and Y' and states it performs side-by-side comparison of 2–5 entities. It distinguishes itself from sibling tools by explicitly urging preference over 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?

The description includes explicit when-to-use guidance ('compare entities'), example queries, and a direct instruction to prefer this tool over alternatives. It also clarifies the entity types and their data sources.

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?

Disclosures beyond annotations: requires account (free/paid), not open-web search, parallel tool routing, returns gaps[] when data unavailable, second-hop iteration, contradictions[], semantic excerpting, expected latency 15-90s. Annotations already declare readOnlyHint, openWorldHint, idempotentHint; description adds critical 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?

Long but well-organized with front-loaded critical info (account requirement, fallback). Every sentence adds value; could be slightly more concise but structure is logical with clear sections.

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 complex tool with no output schema, description covers input, process, output format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field), edge cases (semantic excerpting of large records), and latency. No gaps for agent understanding.

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

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

Schema coverage 100%; description adds value by explaining depth enum values (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and account tier requirement for thorough. Goes 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 'Grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources in ONE call' and distinguishes from siblings like ask_pipeworx. It specifies the verb 'research' and resource 'structured data sources', and contrasts with single-lookup and news tools.

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

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

Explicit guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also gives alternative if not signed in: 'use ask_pipeworx instead'. Clearly states when to use and when not to.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds that results include full input schemas with curated examples and are 'ready to call directly'. No contradictions, though idempotency is implied but not explicitly stated.

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 informative paragraph with clear flow: purpose, usage, return value, advice. Could be slightly more concise (e.g., bullet points for domains) but 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?

Despite no output schema, description fully explains return value: top-N tools with names, descriptions, and full input schemas with curated examples, ready to call directly. Sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, but description adds value by providing examples for query parameter and listing alias names (task, q, description, search) beyond the schema's 'Alias for query' notes.

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 'Find tools by describing the data or task' with specific verb and resource. It distinguishes from sibling tools like deep_research or ask_pipeworx by emphasizing discovery and browsing of available 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?

Contains 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'. Also lists specific domains (SEC filings, FDA drugs, etc.) and mentions it returns options rather than a single answer.

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 important behavioral context: it makes ONE parallel call, mentions the USPTO PatentsView API sunset (May 2025) and soft-fail behavior, and describes the fallback chain (GDELT→GNews). No contradictions with annotations.

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

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

The description is front-loaded with example queries for quick identification. At ~120 words, it is moderately verbose but every sentence adds useful information. The structure flows from examples to purpose to specifics to parameter constraints. Could be slightly tighter, but effective for the complexity.

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

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

Despite having no output schema, the description comprehensively lists return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and addresses edge cases (USPTO sunset, news fallback). For a holistic profile tool, this provides sufficient context for an agent to understand what it will receive.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining what the 'value' parameter accepts (ticker or zero-padded CIK), reinforcing that names are not supported, and providing concrete examples ('AAPL', '0000320193'). This goes slightly beyond the schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and enumerates specific data sources and outputs. It explicitly distinguishes itself from sibling tools like resolve_entity and chain lookups, making its unique value obvious.

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

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

The description specifies exact user queries that trigger this tool (e.g., 'Tell me about X', 'research Acme'), includes a strong recommendation to prefer it over chaining, and clarifies that names are not supported (use resolve_entity first). This provides explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds usage context but does not elaborate on behavioral traits beyond confirming deletion. 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 very concise (2 sentences, 22 words) and front-loaded with the core action. 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?

Given the tool's simplicity (one required parameter), the description covers purpose, usage, and pairing with siblings. Lacks return value info but no output schema expected.

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 single parameter 'key' has a schema description. The tool description does not add further meaning beyond what the schema provides, meeting baseline.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory). It also distinguishes from sibling tools 'remember' and 'recall'.

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

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

It provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with siblings, offering context for when to use vs alternatives, though no explicit exclusion.

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 value by explaining the underlying process: fetches page, extracts title/description/key links, emits standard markdown. This goes beyond what annotations provide.

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

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

Four sentences, no wasted words. The first two sentences state the core action and output, the third gives a quick process summary, and the fourth lists use cases. Extremely 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?

With 2 fully documented parameters, no output schema needed (output is simple text), and annotations fully covering safety and idempotency, the description provides all necessary context. The output description 'single text blob ready to drop at site-root/llms.txt' is sufficient.

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

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

Both parameters (url, max_links) are fully described in the schema with details like default and max. The description reiterates the extraction of title/description/key links but does not add new meaning beyond what the schema already covers.

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

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

The description specifies the exact verb 'Generate' and resource 'llms.txt file' for any URL, clearly distinguishing it from sibling tools like 'scan_competitor_ai_presence' which focuses on auditing rather than generating.

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 concrete use cases (indexing a client's site, drafting own project, auditing competitor), providing clear context for when to use. It does not explicitly mention when not to use or alternatives, but the use cases are sufficient.

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

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

Annotations already declare readOnly and idempotent, but description adds value by specifying that only active subscriptions are returned by default and listing the exact fields in the response.

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, providing all necessary information without any fluff. 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?

With a simple one-parameter tool and annotations covering safety, the description adequately explains what the tool does, what it returns, and when to use it. No output schema needed given the explicit field list.

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

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

Schema covers the one parameter with a description. The description restates the parameter's effect without adding new information beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields. It distinguishes itself from siblings like subscribe and unsubscribe by indicating it is for reviewing 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 when to use: 'review what you're monitoring before adding more or to find an id to cancel,' which provides clear context and alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by stating it's 'Keyless, offline' (no authentication needed, no network calls) and describes the output format. This enriches the 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?

Two sentences cover purpose, output, and key attributes. No unnecessary words, front-loaded with the core action. Highly 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 a single parameter and no output schema, the description adequately describes the return value (version, validity, classification, integer for IPv4). Combined with comprehensive annotations, it provides complete context for tool invocation.

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

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

The input schema fully describes the 'ip' parameter with an example. The description reinforces its meaning by listing the types of IP addresses and the classification details, adding semantic 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 validates and classifies IP addresses for both IPv4 and IPv6, listing specific classification types and mentioning the integer conversion for IPv4. This gives a precise verb and resource, distinguishing it from sibling tools like cidr_info which handles CIDR ranges.

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 'Keyless, offline' which implies no external dependencies, but does not explicitly state when to use this tool over alternatives like cidr_info or other networking tools. Usage context is implied but not explicitly guided.

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

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

Annotations are minimal, but description provides significant behavioral details: rate limit (5 per identifier per day), free, no quota impact, team reviews daily. This goes beyond annotations and helps the agent understand constraints.

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

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

Description is a single paragraph but well-structured, starting with purpose, then usage guidance, and ending with constraints. It is concise with no redundant 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?

For a feedback tool with no output schema, the description covers input requirements, behavior, constraints, and impact. It is fully complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but description adds value by explaining enum values for 'type', suggesting message length (1-2 sentences, 2000 chars), and emphasizing specificity. This complements 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 defines the tool as sending feedback to the Pipeworx team, listing specific types (bug, feature, data_gap, praise). It distinguishes from all sibling tools which are analysis or query tools, not feedback mechanisms.

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 (for bugs, feature requests, data gaps, praise) and what to avoid (pasting end-user prompts). It lacks mention of when not to use this tool, but no sibling tool serves the same purpose, so it's 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 read-only, open-world, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, self-aggregating, and caching duration (5min-1h). 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 concise, uses a clear numbered list for use cases, and immediately states the purpose. Every sentence adds value without redundancy.

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

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

Given the single optional parameter, no output schema, and comprehensive annotations, the description covers everything needed: return value (top tools, packs, volume), data source, caching, privacy, and use cases.

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

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

Although the schema fully documents the 'window' parameter with enum and description, the description adds contextual guidance on how different windows affect results (hot vs. steady-state). This enriches the schema's coverage.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, using specific verbs ('Returns'). It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated trends from other agents.

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 three explicit use cases and explains the trade-off between short and long windows. However, it does not explicitly state when not to use this tool or list specific 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 indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: monotonicity checks, partition_check, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB depth. 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 long but well-structured with clear sections for each mode, semantic anchor, partition filter, response format, and fill check. Could be slightly more concise, but every sentence adds value for a complex tool.

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

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

Given the tool's complexity (multiple modes, internal checks, fill analysis) and absence of output schema, the description is remarkably complete. It explains all input modes, internal algorithms, response fields, and trade discipline. No gaps.

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

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

Schema covers both parameters with descriptions. The description adds significant value: explains the effect of no args (trending_scan), provides example values for event slugs and topic questions, and clarifies the behavior difference between event and topic modes.

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 that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: trending_scan (no args), single-event (event slug), and cross-event (topic). This is specific and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also gives negative guidance: 'do not trade it' when realizable_edge_pp ≤ 0, and suggests alternative tool for custom sizing.

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, and non-destructive. The description adds substantial behavioral context: caching at KV level per knob, response structure with by_segment and diagnostics, and details on model families and tradeable-edge knobs. 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 very long and delves into deep technical details (e.g., model families, Kelly formulas). While informative, it is not concise and could be restructured to front-load essential information. Every sentence does not earn 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 complexity (9 parameters, no output schema), the description covers response structure, caching, diagnostics, and model details. It is thorough but missing an explicit output schema. Still, it provides enough context for an agent.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description does not add significant parameter-specific meaning beyond what is in the 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?

The description states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs like 'scan' and 'return opportunities,' and distinguishes itself from sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) by focusing on broad 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 is built for 'what should I bet on today' and mentions that agents discover opportunities without paging hundreds of markets. It implies usage context but does not explicitly say when not to use or provide alternatives, though siblings are listed.

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 details beyond annotations: history depth bounded by 60-day TTL, decay computed from daily closes not intraday, snapshot gaps meaning no scan that day, and that snapshots are written on cache-miss. No contradictions with annotations.

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

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

The description is front-loaded with the key question and structured with response fields. It is comprehensive but slightly verbose; however, every sentence adds value given the complexity.

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

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

With no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and limits. It covers all necessary aspects for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats default values and constraints already in the schema but adds minimal new context like 'snapshot family' for window. No additional syntax or format details 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering the duration and trend of edges. It distinguishes itself from siblings like `polymarket_edges` by focusing on historical persistence rather than raw snapshots.

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 context on when to use the tool by contrasting 'a fresh wide edge' with a '3-week-old wide edge', implying the tool is for differentiating edge ages. However, it does not explicitly state when not to use it or provide 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 declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: it walks the order-book ladder, returns verdicts (clean/degraded/cannot_fill), warns about forced directional risk and thin legs. 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 fairly long but well-structured with sections for single-market and basket modes, using bold for emphasis. Every sentence adds value, though some details could be moved to an output schema if one existed. For the complexity, it is appropriately 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?

Without an output schema, the description fully covers return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) and explains the tool's role in risk assessment. It is complete for a tool of this 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 description coverage is 100%, so baseline is 3. The description adds significant value by explaining parameter behavior in different modes (e.g., side defaults, size_usd interpretation for buys vs sells, basket settlement notional). This goes beyond what the schema provides, justifying a score above baseline.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and specifies outputs for each. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial basket fills cause directional risk), effectively telling when and when not to use it.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent. Description goes far beyond annotations by detailing two modes, compatibility_warning conditions (matched_pairs:0 scenarios), temporal alignment, and skipped cross-type/subtype counters. 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 comprehensive but somewhat lengthy; however, every sentence adds value. Front-loaded with core purpose and modes, then details safety fields. Could be slightly more concise, but information density is high and structure is logical.

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 (cross-venue, two modes, safety fields, temporal alignment) and lack of output schema, the description is remarkably complete. It covers all necessary aspects: usage, parameter behavior, output structure (response fields), and edge cases like compatibility issues.

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 3 parameters documented), but description adds significant value: explains topic parameter values and how they map, clarifies that explicit tickers override topic-mapped sides, and provides usage examples. Goes beyond schema by giving context for each parameter.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from sibling tools like polymarket_arbitrage by explicitly focusing on cross-venue comparison and detailing two modes (topic shortcuts and explicit tickers).

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

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

Explains when to use topic mode vs explicit ticker mode, and warns that most pre-mapped topics currently return compatibility_warning. Provides safety fields (compatibility_warning, temporal_alignment) to guide appropriate use. Lacks explicit 'when NOT to use' but the warnings effectively convey that not all topics yield tradeable spreads.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and pairing info, which is valuable 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, no wasted words. Front-loaded with core purpose, then usage guidance, then context. Ideal structure.

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 retrieval tool with good annotations, the description covers purpose, param behavior, and use case. No output schema but fine given simplicity.

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 meaning: omitting key lists all keys, clarifies key is a memory key. Adds behavioral nuance 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 states specific verb+resource: 'Retrieve a value' or 'list all saved keys'. Clearly 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?

Explicitly says when to use (look up stored context) and mentions pairing with remember/forget. Could add 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?

Adds context beyond annotations: explains mark_read behavior (flags events read so next call shows only newer), result content (source, citation_uri, raw event payload). No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Concise, front-loaded with main purpose. Each sentence adds value. No extraneous text.

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 tool with full schema coverage, the description explains return content and behavior. No output schema needed. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for type, since, mark_read, unread_only, and describes result structure. Exceeds baseline.

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

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

Specifically states it pulls fired events from subscription feed, returns recent alerts with source, citation_uri, raw payload. Distinct from sibling tools like list_subscriptions by focusing on reading 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?

Clearly describes when to use with type, since, mark_read, unread_only filters. Mentions polling works and points to an alternative endpoint for scripts. Does not explicitly state when not to use but provides sufficient 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 declare the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: parallelism, fan-out to multiple sources, fallback logic (GDELT→GNews), USPTO soft-fail, and the response format with 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 a single, dense paragraph that front-loads the purpose and examples. While every sentence adds value, the length is slightly high due to the need to cover multiple sources and fallback behavior. However, it remains well-structured and concise given the tool's complexity.

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

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

The description covers all essential aspects: purpose, sources, fallback, parameter details, and return format. It addresses edge cases (USPTO sunset, GDELT→GNews fallback). With no output schema, the description compensates by describing the response structure. The tool is fully documented for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains the 'type' constraint, gives ISO and relative examples for 'since', and suggests typical values like '30d' or '1m'. It also clarifies that 'value' accepts tickers or CIKs.

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 recent window, using multiple data sources (SEC, GDELT/GNews, USPTO). It gives concrete query examples and distinguishes itself from the sibling tool 'entity_profile' by specifying when to use that instead.

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 includes explicit usage scenarios ('What's new with X', 'latest on Y') and provides a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This 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 only say idempotentHint=true and destructiveHint=false. The description adds key behavioral details: scoping by identifier, retention periods (24h for anonymous, persistent for authenticated), and pairing with recall/forget, all beyond what annotations provide.

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

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

Four sentences, no wasted words. First sentence immediately communicates the core purpose, and subsequent sentences add essential context in a logical order.

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 key-value store with no output schema, the description covers purpose, usage, scope, lifetime, and relationships with sibling tools (recall/forget), providing complete context for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful examples for key and value (e.g., 'subject_property', 'target_ticker'), which helps the agent understand appropriate usage beyond mere schema 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 that the tool saves data for later reuse, giving specific examples (ticker, address, preference) and distinguishing it from sibling tools by mentioning 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 says 'Use when you discover something worth carrying forward' and provides context for when not to use it (by mentioning that retrieval/removal is handled by recall/forget).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; the description adds value by disclosing that each call cascades through multiple internal lookups, replacing 2-3 manual steps. 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, well-structured paragraph front-loaded with query examples, then listing supported types and outputs. Every sentence contributes without redundancy.

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

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

With no output schema, the description covers return values for both entity types, mentions citation URIs, and explains internal behavior. Given the tool's complexity (2 params, annotations present), this is fully complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description gives examples (e.g., 'AAPL', 'ozempic') and explains return values per type, adding minor semantic enrichment 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 explicitly states the tool resolves user-spoken names to canonical identifiers, lists supported types (company, drug) with specific outputs (ticker, CIK, RxCUI), and differentiates from sibling tools like compare_entities or entity_profile.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not explicitly mention when not to use or name alternatives, but the directive is strong 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 indicate read-only, idempotent, not destructive. The description adds that it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. It also notes the first entry is treated as the 'subject' for narrative, which is useful 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 concise and well-structured: first sentence states purpose, second explains method, third gives a use case, fourth describes output. No extraneous 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 (multiple entities, ranking, multiple models), the description covers its operation, input parameters, and output fields (score, confidence, signal density). Even without an output schema, it provides sufficient details for an agent to understand the expected result.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying the default model ('workers-ai' when omitted) and the special handling of the first entity as the subject, which supplements 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 compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and surfaces most/least recognized. It distinguishes from the sibling ai_visibility_check which likely handles single entities.

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

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

The description explicitly mentions use for competitive AI-marketing audits and gives an example question. It implies when to use but does not explicitly state when not to or list alternatives, though the use case 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 significant behavioral context beyond annotations: it fans out across two external services, details expected fields in the summary block, explains partial failure behavior (sources_failed list), and warns about first-measurement latency. No contradiction with readOnlyHint/idiompotentHint.

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

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

The description is front-loaded with the core purpose in the first sentence and each subsequent sentence adds value. However, it is slightly verbose (e.g., listing all return fields inline rather than referencing the output schema, which is missing). Still, the structure is clear and well-organized.

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

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

With no output schema, the description fully details return fields (summary block, per-advisory detail, links, alternative versions) and error handling (sources_failed). It covers scope, behavior, and limitations completely 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%, providing baseline 3. The description adds meaning by explaining how the parameters drive the composite check (e.g., version defaults to latest, scoped packages accepted). While not detailing each parameter's syntax, it clarifies their role 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 uses a specific verb+resource ('scan dependency') and clearly states it's a composite check for adding npm packages. It distinguishes itself from siblings by its unique functionality (fans out across deps.dev and bundlephobia) and explicit scope (NPM ecosystem only).

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 the tool: when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides exclusions (other ecosystems fall under deps.dev:version directly) and notes partial failures (bundlephobia can take 5-30s).

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavior: truncation at 200K chars flagged, BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, and passage offsets for verification—greatly exceeding annotation basics.

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-structured: purpose first, then usage, then technical details. Every sentence is informative, though slightly verbose. Could be tightened slightly but remains 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 the tool's moderate complexity (3 parameters, no enums, no output schema but description mentions return format), the description covers purpose, usage, technical implementation, limitations (200K cap), and pairing with sibling tools. Complete enough for confident use by an LLM.

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 3 parameters have descriptions). The description adds value beyond schema by providing examples for query, clarifying the text max, and implicitly explaining limit. This enriches parameter understanding.

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

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

The description specifies 'Semantic search INSIDE a fetched record', clearly stating the verb (search), resource (text inside a record), and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching whole documents.

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 tells when to use: 'Use when the record is too big to cram into the prompt — search_within saves context...' and provides pairing guidance with ask_pipeworx_grounded. No explicit 'when not to', but the context is clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true), the description adds rich behavioral context: subscription persistence, return of new ID, delivery channel behaviors (feed always on, webhook HMAC signing and auto-disable, SMS verification requirement). 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 well-structured: purpose, requirements, types, delivery channels. It is front-loaded with the main purpose and return value. While it is long, every sentence provides necessary detail for a complex tool; could be slightly more concise but remains 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 (3 params, nested objects, no output schema), the description covers most aspects: requirements, all types with examples, delivery channels, and important limitations. However, it does not specify the output structure beyond returning an ID, which is acceptable but could be more complete.

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

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

Schema coverage is 100% but the description adds substantial meaning: it explains each subscription type with real examples (e.g., sec_8k with items, polymarket_edge with topic) and delivery options with detailed behavior (SMS verification, webhook signing). This goes well 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 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb (create) and resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies that an OAuth account is required and that anonymous users cannot persist subscriptions, giving clear when-to-use and when-not-to-use guidance. It also details delivery channels and limitations (e.g., SMS 10/day cap), though it doesn't explicitly compare with sibling tools.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent. Description adds valuable behavioral context: returns live examples with exact tool signatures, can be focused via topic parameter, and serves as an onboarding entry point.

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 front-loaded with common queries, then purpose, return format, usage, and when-to-use. 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?

Despite no output schema, the description fully explains the return structure (category-bucketed examples with tool shapes) and usage patterns, making it complete for its simplicity.

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

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

Schema coverage is 100% with a clear description. The description enriches it by listing example topics and explaining that omitting the parameter gives a full spread, going beyond the schema text.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding. It distinguishes from sibling meta-tools like 'ask_pipeworx' and 'entity_profile', making the unique purpose explicit.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call meta-tools, providing clear when-to-use and alternatives.

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

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

Annotations provide hints (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This goes beyond annotations and fully discloses 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?

Two sentences, front-loaded with the primary action, and efficient. 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 tool's simplicity (one parameter, no output schema), the description covers purpose, ownership, side effects, and mentions related tool 'recent_alerts'. It is sufficient for effective use.

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 one parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' Schema coverage is 100%, so the baseline is 3. The description does not add additional semantic value beyond what the schema already provides.

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

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

The description clearly states 'Cancel a subscription by id' which is a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by explaining ownership enforcement and the deactivation behavior.

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

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

The description explains ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. However, it does not explicitly mention when not to use it or suggest alternatives, though the sibling list makes 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?

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: it explains the two verification paths, return values (verdict with five categories, actual value with citation, reasoning), tolerance parameter behavior, and how it handles different claim types. 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 a single coherent paragraph that front-loads trigger phrases and quickly moves to behavior. It is informative without being verbose, but could be slightly more structured with bullet points or sections for easier scanning. Nonetheless, 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 no output schema, the description fully explains return values (verdict, value, citation, reasoning). It covers all aspects of the tool: parameters, two processing paths, supported claims, and use cases. No gaps identified for an agent to use it correctly.

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

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

Schema covers both parameters (100% coverage). The description enhances understanding by providing examples for 'claim' and explaining the use of 'tolerance_pct' for hallucination detection and default behavior (overriding implied tolerance, cap at 5). This adds practical guidance 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 clearly states it is for 'natural-language claim verification against authoritative sources,' provides specific trigger phrases, and distinguishes itself from other tools by noting it replaces multiple sequential calls. It also differentiates between financial and other claims, giving a clear scope.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides context on the two processing paths but does not explicitly list when not to use it or name alternative tools. However, the context is sufficiently clear for an agent to decide.

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