Arcgis Roanoke

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: default model is free, Anthropic requires BYO key, and output includes per-model fields plus combined view. 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, well-structured paragraph starting with the main purpose, then detailing optional parameters and use cases. 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?

For a tool with 4 parameters, no output schema, and moderate complexity, the description covers all essential aspects: input, output format, cost implications, and typical use cases. It is self-sufficient.

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

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

Schema description coverage is 100%; all four parameters have clear descriptions. The description adds minimal extra meaning (e.g., 'You pay Anthropic directly'), but the schema already documents the parameters well. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and provides a visibility score. It specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. This differentiates it from siblings like 'scan_competitor_ai_presence' by focusing on score plus raw response.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also explains when to use the API key. However, it does not explicitly mention when not to use this tool or name alternative tools for different needs.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context about routing to 5,011 tools and returning structured answers with citation URIs. It does not contradict annotations and provides meaningful extra detail, though it could mention potential limitations like vague queries.

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

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

The description is longer than average but every sentence adds value. It front-loads the main instruction (prefer over web search) and quickly moves to guidance and examples. It is well-structured for the complexity of the tool, though minor repetition exists (e.g., mentioning news twice).

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

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

Given no output schema, the description adequately explains the return value ('structured answer with stable citation URIs') and provides extensive examples. It covers what to ask, when to use alternatives, and the tool's internal routing. It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with all parameters (including aliases) described in the schema. The tool description does not add new parameter meaning beyond the schema's 'Your question or request in natural language' and examples. This meets the baseline but adds no extra depth.

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

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

The description clearly states the tool's purpose: to answer factual questions about current/historical data from authoritative sources, with specific examples like SEC filings, FDA data, and economics. It distinguishes from siblings by advising when to use ask_pipeworx_grounded or deep_research. The verb 'ask' and resource 'Pipeworx' are well-defined.

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

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

Explicit guidance is given: prefer over web search, use for specific query types (e.g., 'what is', 'look up'), and step up to alternatives for hallucination-resistance or broad questions. Examples provided for appropriate usage. This is thorough and actionable.

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

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

The description discloses key behavioral traits: the source-preference ranking (e.g., naming a source boosts it), that it is a fully working router, and that it falls back to nothing. Annotations already indicate readOnly and idempotent; the description adds routing behavior without contradiction.

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

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

The description is informative and well-structured, starting with the beta status and key differences, then usage guidance, and a clarifying note. Every sentence contributes value, though slightly verbose, it remains efficient.

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

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

Given the tool's complexity as a router with thousands of tools and no output schema, the description adequately covers the experimental nature, routing behavior, and usage context. It is complete enough for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with all parameters described, so the description's redundancy about accepting natural language adds little value. The description does not elaborate on parameter usage beyond what the schema provides, meeting the baseline for high 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 it is a beta version of ask_pipeworx, an identical universal router with the same 5,011 tools. It distinguishes itself by mentioning the source-preference ranking improvement and experimental status, making it easy to differentiate from siblings like ask_pipeworx and ask_pipeworx_grounded.

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

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

The description explicitly advises to use this tool 'when you want the newest routing' and notes it is compared against the stable router. It implies ask_pipeworx is the stable alternative but does not explicitly state when not to use this beta version, providing clear context but lacking exclusions.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the return structure, refusal reasons, and extra LLM call cost, providing comprehensive behavioral insight with no contradictions.

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

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

The description is front-loaded with purpose and process, then provides return format and usage guidance. While not extremely concise, 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?

Despite lacking an output schema, the description fully specifies the return object and failure modes, covering all necessary context for a high-stakes grounding tool among many siblings.

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 parameters. The description adds general purpose but no specific details beyond 'natural language question,' which is adequate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads,' distinguishing it from ask_pipeworx by explaining the extraction process and return format.

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

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

It explicitly states when to use (answers that will be quoted, cited, or acted on) and when to prefer the sibling ask_pipeworx (casual lookups), including cost trade-offs and examples.

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 is extremely transparent about the tool's behavior: it resolves markets, classifies bets, fans out to data sources, and includes safety mechanisms like low-confidence resolution short-circuiting and closed-market handling. It explains resolver contract, parent event extraction, news fields, and resolution-rule risk. Annotations already mark it as readOnly and idempotent, and the description adds rich context without contradiction.

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

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

The description is overly long (approx. 500 words) and includes many examples and edge-case explanations. While informative, it lacks conciseness and could be structured more succinctly. Key information is front-loaded but the text is dense.

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 (resolver, fan-out, safety checks, resolution rules), the description is highly complete. It covers all important aspects: input types, behavior, response shapes, safety mechanisms, and edge cases. No output schema exists, but the description explains response fields adequately.

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

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

All three parameters (market, depth, include_raw) have schema descriptions. The tool description adds extra context: it explains depth options ('quick' vs 'thorough') and include_raw's effect on response size, and provides examples for market input. This adds meaning beyond the schema.

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

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

The description clearly states it researches Polymarket bets using Pipeworx data. It specifies the verb 'Research', the resource 'Polymarket bet', and the output 'evidence packet + market-vs-model comparison'. It distinguishes from sibling tools like 'ask_pipeworx' or 'deep_research' by being Polymarket-specific with fan-out logic.

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides detailed examples of fan-outs for various bet types. However, it does not explicitly say when not to use or name alternatives for non-Polymarket queries.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and output format including citation URIs. No contradiction.

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

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

The description is slightly verbose but well-structured with trigger phrases front-loaded. Each sentence adds value, though some redundancy could be trimmed (e.g., 'side-by-side' and 'parallel call'). Still efficient overall.

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

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

Despite no output schema, the description fully explains return values: paired data with citation URIs, sorted by primary metric. It covers edge cases (off-calendar fiscal years) and notes replaces 8-15 sequential lookups. Complete for a comparison tool.

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

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

Both parameters have schema descriptions (100% coverage). The description adds meaning by explaining the data each enum value retrieves and listing acceptable input formats (tickers/CIKs for company, drug names for drug). Slightly more detail on sorting behavior could enhance, but overall strong.

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 the specific verb 'compare' and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It differentiates from sibling tools like entity_profile by emphasizing parallel comparison over single-entity 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 provides clear trigger phrases ('Compare X and Y', 'which is bigger', etc.) and explicitly instructs agents to 'ALWAYS PREFER over sequential single-pack lookups.' It also distinguishes the entity types and their use cases.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds account requirement, paid tier, non-open-web nature, decomposition, gap recovery, contradictions, semantic excerpting, and expected timing. 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?

Very detailed and informative; every sentence adds value. Slightly verbose but still well-structured with key points 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?

Despite no output schema, description fully explains output format, edge cases, limitations, and time expectations, making it complete for effective tool usage.

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

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

Schema descriptions cover both parameters. Description adds significant context on depth behaviors and question decomposition, enhancing understanding 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?

Clearly states it performs grounded multi-source research across structured data sources, returns a findings packet, and distinguishes from ask_pipeworx for single lookups and breaking news.

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

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

Explicitly advises using ask_pipeworx when not signed in, for single lookups, or for breaking/current-news topics. Also describes depth options and when to choose each.

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. The description adds value by explaining the return format (top-N with schemas and examples, ready to call) and the purpose. No contradiction detected.

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 sentence that front-loads the core purpose. Every clause adds essential information (domains, return content, usage guidance). No redundancy.

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

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

Covers the tool's purpose, when to use, and what it returns. Could benefit from mentioning behavior when no results or query is too broad, but for a discovery tool it is largely 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 baseline is 3. The description adds value by providing examples ('analyze housing market trends') and clarifying that query accepts many aliases (task, q, description, search), which enhances usability.

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

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

The description clearly states the verb ('Find') and resource ('tools'), specifies that it works by describing data or task, and lists numerous domains. It distinguishes from sibling tools by positioning itself as the discovery gateway.

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

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

Explicitly states when to use: 'when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and hints at alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds significant behavioral detail: fans out across multiple sources, returns specific structured data, mentions soft-fail for patents (USPTO API sunset), and lists all return fields. This goes beyond annotations to explain internal behavior.

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

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

The description is well-structured: example queries first, then core functionality, then detailed return structure and limitations. It is front-loaded with purpose. However, it repeats the 'names not supported' constraint twice and could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (multi-source, many return fields, no output schema), the description covers key aspects: data sources (SEC, XBRL, USPTO, news, GLEIF), return structure, limitations (patents soft-fail), and prerequisites (resolve_entity for names). It is nearly complete, though missing details on pagination or rate limits, but those are minor given the tool's nature.

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

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

Schema description coverage is 100% and already provides clear explanations for both parameters (type and value). The description primarily reinforces the schema's constraints (e.g., no names) with examples, but adds little new semantic meaning beyond what the schema already offers.

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

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

The description clearly states the tool's purpose: to provide a full cross-source profile of a US public company in one parallel call. It uses concrete examples like 'Tell me about X' and explicitly distinguishes from chaining individual lookups, making it distinct from sibling 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?

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack lookups' for holistic views. Clearly states that names are not supported and recommends using resolve_entity first. Specifies valid inputs (ticker or zero-padded CIK) and when to use 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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data, which justifies deletion reasons. No contradictions.

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

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

Two concise sentences covering purpose, usage, and pairings. No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, usage, and behavioral intent. Could mention error handling or what happens after deletion, but not required for completeness.

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

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

Schema coverage is 100% with a clear parameter description. The description adds no extra meaning beyond 'by key', which is already in the name. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It distinguishes from siblings by mentioning pairing with '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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Names alternative tools for pairing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral details like fetching the page, extracting content, and emitting standard format, which complements the annotations without contradiction.

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

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

The description is concise (3 sentences plus a list) and well-structured, with the core purpose and process upfront. Every sentence adds value, and the bullet list at the end clarifies use cases 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 tool's simplicity (2 parameters, no output schema), the description fully covers purpose, process, output format, and use cases. Annotations adequately address safety and side effects. No further context is necessary.

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

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

Both parameters are fully documented in the input schema (100% coverage). The description adds value by noting max_links defaults (25) and maximum (50), and clarifying that url should be a full URL. This provides context beyond the schema.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL to aid AI crawlers. It specifies the actions (fetch, extract, emit) and the output format. Distinguishes from siblings by focusing on file generation rather than checking AI visibility or competitor analysis.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting your own llms.txt, or auditing a competitor. While it lacks explicit when-not-to-use guidance, the sibling context (e.g., ai_visibility_check) implies alternatives for checking existing presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint true, and destructiveHint false. The description adds the specific information retrieved (fields, geometry type, count, capabilities) 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?

A single sentence front-loads the action and result, listing what the schema contains. Every word is informative with no redundancy.

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

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

For a single-parameter, read-only tool with clear annotations, the description fully covers the return structure (fields, geometry, count, capabilities) and is sufficient for an agent to understand the tool's output.

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 parameter description. The tool description reiterates that it operates 'by url' but doesn't add new semantic details 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 ('Get') and resource ('ArcGIS Feature/Map Service layer's schema') and clearly differentiates from sibling tools like 'query_layer' which likely queries actual data rather than schema.

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 when to use: when needing layer metadata (fields, geometry, count, capabilities) by URL. It doesn't explicitly state when not to use or provide alternatives, but the context is clear given sibling names.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying return fields (id, type, params, etc.) and clarifying that only active subscriptions are returned by default, with the include_inactive parameter to override.

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, immediately front-loading the purpose in the first sentence. Every sentence serves a clear role: function and usage guidance.

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

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

Since there is no output schema, the description compensates by listing return fields. It provides sufficient context for a simple list tool, including usage guidance. Minor missing details like ordering or pagination are not critical.

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

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

Schema description coverage is 100%. The description reinforces the default behavior (active subscriptions) but does not add new information beyond the schema's parameter description.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'unsubscribe' by being a read-only listing tool.

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

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

The description explicitly says to use this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use it. However, it does not explicitly state when not to use it or mention 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 no behavioral hints (all false), so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('signal directly affects roadmap'). This is valuable context beyond what annotations could 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 efficient, combining purpose, usage guidelines, constraints, and instructions in a few sentences. It is front-loaded with the core purpose. Slightly wordy in the middle but no unnecessary information. Could be more structured but overall 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 simplicity (3 params, no output schema), the description covers all key aspects: when to use, how to format, behavior (rate limits, quota, impact). The nested context object is not elaborated in the description but is fully covered by the schema. No missing critical 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 description coverage is 100%, so baseline is 3. The description does not add significant extra meaning beyond what the schema already provides. The parameter details (type enum, message length, context optional) are well-documented in the schema itself, making the description's contribution marginal.

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: sending feedback to the Pipeworx team. It lists specific categories (bug, feature, data_gap, praise) and distinguishes it from all sibling tools which are unrelated to feedback. The verb 'Tell' and resource 'Pipeworx team' are 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 provides explicit when-to-use scenarios: when a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or for praise. It also gives instructions on formatting (describe in terms of tools/packs, don't paste end-user prompt) and mentions rate limits. It lacks explicit when-not-to-use guidelines, but the positive guidance is strong.

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

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

Annotations already indicate read-only, non-destructive behavior. Description adds rich behavioral context: data source (CF analytics-engine), no PII, caching (5min-1h), and that it shows what other agents are calling. This goes well beyond annotations.

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

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

Description is front-loaded with the core function, then lists use cases, then adds data provenance and caching. Every sentence provides value, no fluff.

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

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

For a simple read-only tool with no output schema, the description covers output composition (top tools, packs, volume), data source, caching, privacy, and parameter behavior. Complete.

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

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

Schema coverage is 100% with a single enum parameter. Description adds semantic guidance: shorter windows surface what's hot, longer show steady-state demand, enhancing the schema's bare enum.

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

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

Description clearly states the tool returns top tools, packs, and call volume over a window. Verb 'returns' and resource 'trending data' are specific. Distinguishes from siblings like discover_tools by focusing on current call volume.

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?

Lists three explicit use cases for when to use the tool (discovering hot data, confirming canonical tools, checking alignment). Does not explicitly mention when not to use or alternatives, 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?

Annotations declare read-only, idempotent, non-destructive behavior. Description adds extensive behavioral context: scanning, monotonicity violations, partition checks, semantic anchor with Jaccard similarity, partition filter, fill check against live CLOB depth, and output structure. No contradictions with annotations.

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

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

Description is dense and well-structured, with front-loaded key information. Every sentence adds value, though it could be slightly more concise. Still, given the complexity, the length is 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?

No output schema provided, so description compensates by detailing response fields (opportunities[], partition_check, fill check results) and edge cases (skipped_low_similarity, placeholders_filtered). Covers all major aspects needed for correct tool invocation.

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

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

Schema coverage is 100%, but description adds significant meaning: explains event slug format, accepts full URLs, describes topic as seed question, and details behavior with no arguments. Provides concrete examples and clarifies the purpose of each parameter beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach and usage modes.

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 on when to use each mode: no args for trending_scan, 'event' for specific market, 'topic' for cross-event scanning. Provides examples and explains that cross-event mode catches patterns missed by single-event. Also includes a fill check warning to avoid trading when realizable edge is non-positive.

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 safe read-only, idempotent behavior. The description adds substantial context: caching policy (KV-level 1h), response structure (by_segment, _diagnostics, fed_candidates), and edge calculation details. 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 verbose but well-structured, with clear sections for segments, knobs, and response. Every sentence adds useful information, though a slightly more condensed version could improve readability.

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

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

With no output schema, the description thoroughly explains the response structure, edge fields, diagnostics, and caching. It covers all needed context for an agent to understand and 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%, providing baseline. The description adds significant value beyond schema by explaining nuances (e.g., min_partition_leg_kelly's behavior with partition arbs, slippage_pp fees, min_edge_pp filtering net of slippage).

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using specific model families. This clearly distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description frames the tool for 'what should I bet on today' and details tradeable-edge knobs. It lacks explicit when-not-to-use guidance or comparisons to sibling tools, but provides sufficient context for typical use.

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

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

The annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: returned arrays (tracked, expired, snapshot_dates), computation of trend and decay, and limitations (snapshot TTL, daily closes). No contradiction with annotations.

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

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

The description is long but front-loaded with purpose and packed with valuable information. Every sentence contributes meaning, though it could be slightly more concise without losing clarity.

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

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

Given the absence of an output schema, the description thoroughly explains return values (tracked, expired, snapshot_dates) and their fields, computation details, and limitations. This makes the tool's behavior fully understandable for an agent.

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

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

The input schema already describes both parameters with 100% coverage. The description adds usage context (default values, clamping) and explains how they affect the query, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question of how long an edge has existed and whether it is shrinking, distinguishing it from sibling tools like polymarket_edges which likely provide raw edge data.

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

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

The description implies when to use the tool by contrasting fresh edges with older ones. It explains the output structure and limits (e.g., history depth, decay from daily closes). However, it does not explicitly state alternatives 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details beyond these: it is a read-only check (no state modification), explains what happens with partial fills (unhedged directional position), and lists return fields including 'forced_directional_risk'. No contradiction with annotations.

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

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

The description is thorough but verbose. It is well-structured with clear sections (single-market, basket, usage), but some information is repeated (e.g., side defaults mentioned twice). Could be streamlined without losing essential content.

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

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

Given the complexity of two modes and many return fields, the description covers all necessary aspects: mode selection, parameter behavior, return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). No output schema exists, so the description compensates fully.

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 schema already describes all 4 parameters. The description adds value by explaining how 'side' behaves differently in single-market vs basket mode, how 'size_usd' is interpreted (spend vs target proceeds for single, settlement notional for basket), and default values and clamping. This contextual guidance is beneficial beyond the schema.

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

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

The description clearly states the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, specifies outputs like verdict and slippage, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on risk checking before acting on signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why (theoretical overround on thin books not capturable, partial fills convert arb to directional risk), providing clear context and exclusion 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. The description adds extensive behavioral details: computation of per-venue prices and matched spreads, safety fields (compatibility_warning, temporal_alignment), and counters for skipped cross-type comparisons. It also discloses that most shortcuts are not tradeable, enhancing transparency.

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

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

The description is dense but well-structured: front-loads purpose, clearly separates modes, response format, and safety fields. Every sentence adds value without redundancy. It is appropriately sized 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 no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and covers edge cases like compatibility_warning conditions and temporal alignment. It thoroughly addresses potential uncertainties for the 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?

All three parameters are described in the schema (100% coverage). The description adds context by explaining the two modes and parameter interactions (override behavior), and provides examples. It clarifies the meaning and boundaries beyond schema descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description explains when to use each mode (topic shortcuts vs explicit), warns that most pre-mapped topics are not tradeable, and highlights temporal alignment as a prerequisite for meaningful spreads. It lacks explicit 'when not to use' or alternatives, but provides sufficient context for appropriate invocation.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns 'attribute rows (and geometry)', aligning with annotations. No contradictions. Adds behavioral context beyond annotations by describing return structure and usage examples.

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 short, targeted sentences. No fluff. Front-loads main purpose and key details. Each sentence adds essential info: purpose, parameters, example usage.

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?

All 6 parameters are covered. Without output schema, description explains return type (attribute rows and geometry). Could mention pagination nuance or geometry flag, but overall sufficient for a query tool with clean annotations.

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

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

With 100% schema coverage, baseline is 3. Description enhances parameter meaning by providing SQL-like syntax examples (where, order_by, out_fields), default values (limit 50, where '1=1', out_fields '*'), and URL format requirement. Adds significant value beyond schema descriptions.

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

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

The description clearly states the verb 'Query', the resource 'ArcGIS Feature Service / Map Service layer', and specifies it's for data retrieval using SQL-like parameters. It distinguishes from sibling tools like search_datasets which finds layers, and layer_info which likely gets metadata.

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

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

Provides clear usage context: URL comes from search_datasets, SQL-like parameters, and example for sampling (where='1=1', out_fields='*'). However, it lacks explicit when-not guidance or alternatives among siblings, though the narrow focus implies its specific use case.

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

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

Discloses scoping behavior (anonymous IP, BYO key hash, account ID) beyond annotations. Consistent with readOnlyHint and idempotentHint. No mention of rate limits or error handling, but adds useful 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?

Concise, front-loaded, every sentence adds value. Four sentences cover purpose, usage, scoping, and pairing with siblings 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?

For a simple tool with one optional parameter and no output schema, the description is complete. Covers purpose, usage, parameter semantics, and behavioral context.

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

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

Schema coverage 100% and description adds meaning: omitting key lists all keys. Provides examples in schema definition but description reinforces and clarifies behavior.

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

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

Clearly states the tool retrieves a saved value or lists all keys. Explicitly distinguishes from sibling tools remember and forget, and provides concrete examples (ticker, address, research notes).

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

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

Provides clear context for when to use (look up stored context), mentions alternatives (remember to save, forget to delete). Could explicitly state when not to use, but sufficient for typical retrieval scenario.

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

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

Description mentions mark_read parameter that modifies read state, contradicting annotation readOnlyHint: true which implies no side effects. This is a critical inconsistency. Also fails to disclose other behavioral details.

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

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

Two concise sentences packed with key info: purpose, returned fields, filtering, mark_read behavior, alternative access. Front-loaded with purpose. Efficient use of space.

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

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

Given no output schema, description adequately explains return content and key parameters. Covers filtering, mark_read side effect, and alternative endpoint. Lacks pagination details but schema covers limit.

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 descriptions already cover each parameter comprehensively (100% coverage). The description adds some usage context (e.g., mark_read affects next call) but does not add significant new meaning beyond schema.

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

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

Clearly states 'Pull fired events from your subscription feed', identifies resource and action. Lists key fields returned (source, citation_uri, raw payload). Distinct from siblings like list_subscriptions.

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

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

Explains filtering by type and ISO timestamp, mentions polling works, and points to an alternative HTTP endpoint for scripts/dashboards. Does not explicitly state when not to use, but provides good usage context.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant context: fan-out to multiple sources, GDELT→GNews fallback, PatentsView API sunset soft-fail, return structure, and 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?

Though relatively long, the description is well-structured and front-loaded with example queries. Every sentence serves a purpose, but minor redundancy could be trimmed (e.g., repeating 'fan out' details). Still, it earns its length.

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

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

Given moderate complexity and no output schema, the description covers main behavioral aspects (sources, fallback, parameter formats, return structure). It does not mention pagination or limits, but overall it is sufficiently complete for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful usage context: examples of 'since' values (ISO date and relative shorthand), explanation that type only supports 'company', and that value can be ticker or CIK. This exceeds the 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 returns a change feed for a company, fanning out to multiple sources. It provides specific query patterns like 'What's new with X' and explicitly distinguishes from the sibling tool 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 gives explicit when-to-use scenarios (e.g., 'latest on Y'), when not to use (static profile queries), and names the alternative tool (entity_profile). It also explains fallback behavior for news sources, providing comprehensive guidance.

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

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

Annotations already indicate idempotent and non-destructive. Description adds context about persistence duration (24h for anonymous, persistent for authenticated) and scoping by identifier, which is 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 informative but compact, covering purpose, usage, behavior, and pairing. Every sentence adds value, though slightly verbose for some may be a minor issue.

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 fully covers behavior, persistence, scoping, and relationship to sibling tools. 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 100% of parameters with descriptions. Description adds concrete examples (e.g., 'subject_property', 'target_ticker') and context on usage, enhancing understanding 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 saves data for reuse across conversations or sessions, with specific examples. It distinguishes from siblings recall and forget.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. Also mentions pairing with recall and forget, providing clear guidance.

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds that it cascades through multiple endpoints, returns specific fields per type, and auto-disambiguates for companies—valuable 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?

The description is concise, front-loaded with example questions, and 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?

Despite no output schema, the description fully explains return values per entity type, including citation URIs. All necessary context is provided for correct usage.

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

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

Schema covers both parameters with descriptions. The description adds real-world examples (e.g., 'AAPL', 'ozempic') and clarifies that company value accepts ticker, CIK, or name, going beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, with concrete examples (ticker, CIK, RxCUI). It distinguishes itself from sibling tools like 'entity_profile' by focusing on ID lookup rather than profile details.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides context that it replaces 2-3 manual lookups, though it doesn't explicitly state 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds that it internally calls ai_visibility_check, ranks results, and returns 'score, confidence, signal density'. This is sufficient behavioral context beyond annotations, though no edge cases or performance details are given.

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 with an example embedded. It is front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side') and every sentence adds value. No redundancy or fluff.

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

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

Given the tool's complexity (composite of ai_visibility_check, 4 parameters, no output schema), the description adequately explains purpose, process, and return fields. However, it does not clarify ranking algorithm or the meaning of 'signal density', leaving minor gaps for a first-time user.

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

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

Schema coverage is 100%, so parameters are well-documented. The description adds that the first entity is treated as 'subject' for narrative, and implies that 'models' includes 'workers-ai' default and 'anthropic' requiring _apiKey. This enriches the schema's descriptions without replacing them.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and defines the resource as 'AI visibility across multiple entities'. It clearly distinguishes from siblings by referencing the underlying ai_visibility_check and the competitive audit use case, avoiding confusion with general comparison tools like compare_entities.

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

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

The description explicitly states the tool is 'useful for competitive AI-marketing audits' and gives an example question. It implies the tool requires 2-8 entities (from schema) and that first entity is the subject. While it doesn't explicitly mention alternatives, the sibling list and context (e.g., ai_visibility_check for single entities) provide implicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral detail: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed listed if timeout. No contradiction with annotations.

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

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

Front-loaded with a clear summary sentence. Subsequent details are valuable and well-structured, though slightly verbose. Earns its space with specifics on composite behavior and partial failures.

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

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

Given complexity (multiple data sources, partial failures, no output schema), description covers composite check, return fields listed, degradation behavior, and ecosystem scope. Complete enough for effective tool selection.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add new meaning beyond schema; it reiterates package name acceptance of scoped packages which is already in the schema description.

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

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

Description clearly states it is a composite check for 'should I add this npm package' covering license, advisories, version history, bundle size, etc. It distinguishes from siblings by being a single-call aggregator across deps.dev and bundlephobia.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes NPM-only in v1 and directs other ecosystems to deps.dev:version directly, providing clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the specific fields returned (name, summary, record_count, owner/org, url), which is helpful behavioral context beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and each sentence earns its place. No wasted words.

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

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

Despite having no output schema, the description compensates by listing the return fields and the downstream usage. Given the tool's simplicity (search with optional filters), this is complete.

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

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

Schema coverage is 100%, so the description does not need to document parameters. However, it adds meaning by specifying the default organization (City of Roanoke GIS) and hints that 'org_id' can override it, providing context not in the schema.

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

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

Description starts with a specific verb ('Search') and clearly identifies the resource ('City of Roanoke GIS open geospatial datasets'). It lists the types of datasets (parcels, zoning, public works) and specifies what the return contains, effectively distinguishing from sibling tools like query_layer and layer_info.

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

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

The description explicitly states when to use this tool (to search datasets by keyword) and provides guidance on what to do with the results (pass the url to query_layer or layer_info). It does not explicitly state when not to use it or name alternatives, but the context is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), it discloses embedding model (BGE-base-en), window size (500-char overlapping windows), character offsets, similarity scores, and 200K char cap with truncation flag. No contradiction with annotations.

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

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

Three sentences front-loaded with purpose; efficient but could slightly tighten wording without losing detail.

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

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

Given no output schema, description fully explains return format (passages with offsets and scores), constraints (cap, truncation), and model details. Pairs with sibling tool, making it complete.

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

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

Schema coverage is 100%, but description enhances parameters by providing natural-language query examples and clarifying text as document text and limit as max passages. Adds value beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, specifying input ('text you already pulled') and output ('top-N passages with character offsets and similarity scores'). It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use ('when the record is too big to cram into the prompt') and pairs with ask_pipeworx_grounded. Could be more explicit about 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?

Beyond annotations (which indicate non-read-only, open-world, idempotent, non-destructive), the description adds critical behavioral details: returns a subscription id, requires OAuth, delivery channel specifics, SMS cap of 10/day, webhook auto-disable after 10 failures, and that the webhook secret is returned only once.

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 front-loads the main purpose, then lists supported types and delivery channels with examples. It is somewhat lengthy but justified by the tool's complexity. Could be slightly more concise.

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

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

No output schema exists, but the description mentions the return value ('Returns the new subscription id'). It covers prerequisites (OAuth account), behavioral constraints (SMS cap, webhook auto-disable), and delivery options. Fully addresses the tool's complexity.

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

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

Schema coverage is 100%, but the description significantly augments it by providing type-specific parameter examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'), clarifications (e.g., 'sponsor or condition required' for clinical_trial), and delivery channel details like SMS verification and webhook signing.

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 ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by specifying the creation aspect.

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

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

The description provides clear context by listing supported types and delivery options, and mentions the requirement for a Pipeworx OAuth account. However, it does not explicitly state when not to use this tool or suggest alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context about the output (example questions with tool shapes) and the source (live catalog), complementing the annotations without contradiction.

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

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

The description is front-loaded with key phrases like 'onboarding entry point' and includes examples of input queries. It is structured with categories, usage instructions, and a clear call to action. 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 that there is no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument shapes). It covers the purpose, usage, parameters, and output, making it fully complete for an agent to select and invoke 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% for the single optional parameter. The description adds value by listing the allowed topic values (finance, pharma, etc.) and explaining the behavior of omitting the parameter (returns full spread). This goes beyond the schema's basic description.

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

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

The description clearly states that this tool is the onboarding entry point for an agent, returning category-bucketed example questions with exact tool+argument shapes. It explicitly distinguishes itself from sibling tools by advising to use this FIRST when you don't know what Pipeworx can do.

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

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

The description provides explicit guidance: use this tool first when you don't know Pipeworx's capabilities, call with no arguments for a full spread, or pass a specific topic to focus. It also notes this tool helps learn how to call meta-tools like ask_pipeworx.

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 value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events stay available via recent_alerts. No contradiction with annotations.

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

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

Three concise sentences, each adding unique information. Front-loaded with the main action.

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

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

For a single-parameter idempotent tool, the description covers the action, ownership, and data retention. Complete given the tool's 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% and already describes the id parameter clearly. The description adds no further parameter meaning beyond saying 'by id'.

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 sibling tools like subscribe and list_subscriptions by explaining 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?

It explains ownership enforcement and that historical events remain available, guiding the agent when to use this tool. However, it does not explicitly state alternatives 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating safe, idempotent, and non-destructive behavior. The description adds behavioral context: exact percent-delta math for financial claims, fall-through to grounded pipeline for others, and return of verdict, actual value with pipeworx:// citation, and reasoning. No contradictions with annotations.

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

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

The description is moderately long but front-loaded with trigger phrases and every sentence adds value. It efficiently covers purpose, usage, parameter nuance, and return format. Minor redundancy could be removed, but overall it is well-structured and informative.

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

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

Given the tool's complexity (two pipelines, no output schema), the description is remarkably complete. It explains the two processing paths, return format (verdict, actual value, citation, reasoning), and parameter usage. Without an output schema, the description fully covers what the agent can expect, making it complete for 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?

Input schema has 2 parameters with 100% description coverage. The description adds meaning beyond the schema: for 'claim', it clarifies the natural-language format; for 'tolerance_pct', it explains default (implied by wording, capped at 5) and overrides (e.g., 1-2 for hallucination detection). This is valuable context not present in the schema alone.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries ('Is it true that...', 'fact check') and distinguishes between company-financial claims (via SEC EDGAR) and other claims (routed to grounded pipeline). It also describes the return values (verdict, value, citation, reasoning), making its role distinct from sibling tools like 'deep_research' or 'ask_pipeworx_grounded'.

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

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

The description explicitly specifies when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further divides usage into two categories (company-financial via structured path, others via grounded pipeline). While it does not explicitly list when not to use it, the context is strong enough for an agent to differentiate from open-ended research tools.

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