Arcgis Peterborough

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

Annotations declare read-only, idempotent, non-destructive. Description adds behavioral details: default model, cost implications for Anthropic, return structure (per-model + combined). 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?

Four sentences, front-loaded with core purpose. Each sentence adds value: purpose, default model, return format, use cases. 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 all parameters with extra context, describes return shape despite no output schema, and mentions use cases. Could elaborate on confidence/signals but sufficient for typical use.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: explains default model behavior, when _apiKey is needed, and context usage for disambiguation. Exceeds baseline of 3.

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

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

Description clearly states the verb 'probe' and 'score' with specific resources (LLMs, visibility) and scope. Distinguishes from siblings by focusing on LLM visibility scoring with default model and BYO key option, as opposed to other research or monitoring 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?

Describes use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but lacks explicit exclusion or comparison to sibling tools like scan_competitor_ai_presence. Provides context for when to use.

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

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

Discloses routing to 4,552 tools, citation URIs, and that it works on all tiers with one fast call. Annotations already indicate read-only, open-world, idempotent; description adds 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?

Front-loaded with key message, includes examples and sibling differentiation. Slightly long but each sentence adds value; could be more structured but effective for its purpose.

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

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

Given the complexity (4552 tools, no output schema), description fully covers purpose, usage, and behavior. No gaps remain for an AI agent to misunderstand.

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 parameter descriptions present. Description does not add extra meaning beyond examples; schema already explains the question parameter. 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's purpose: answering factual questions using authoritative structured data, with examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It distinguishes from siblings by being the default entry point.

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 (for factual questions, preferring over web search) and when to step up to grounded or deep research tools. Provides concrete examples and phrases like 'what is', 'look up', 'find'.

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

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

Description adds extensive context beyond annotations: explains the extraction process, return structure with answer/evidence/confidence/source/refusal_reason, lists specific refusal reasons, and notes extra LLM cost. Annotations only provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so description significantly enhances 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?

Description is somewhat long but front-loaded with key purpose and usage. Every sentence adds value: purpose, routing, extraction process, return format, refusal reasons, cost trade-off. Could be slightly more concise but overall efficient.

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

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

Given the complexity of the tool (routing over 4,552 tools, extraction, refusal logic) and no output schema, the description is remarkably complete. It explains what happens on success and failure, lists refusal reasons, and covers the return structure. A human or agent would have full understanding of the tool's behavior.

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 6 parameters documented, so baseline is 3. Description adds value by listing alias fields and explaining the overall routing and extraction process, but doesn't add additional detail about each parameter beyond aliases. Hence 4.

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

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

Description states it's a 'hallucination-resistant answer mode for high-stakes reads', clearly distinguishing from the sibling 'ask_pipeworx' by specifying the grounded, extraction-based behavior. The verb 'Extracts answer using ONLY what the tool result contains' explicitly defines the action.

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

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

Description explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups', providing clear when-to-use and when-not-to guidance with alternative.

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

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

Annotations (readOnlyHint, idempotentHint) are non-contradictory. Description adds rich behavioral context: fan-out process, resolver contract, parent event extraction, safety mechanisms (low-confidence suppression, closed market handling), and resolution rule risk analysis.

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

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

The description is long but well-structured with all-caps section headers, front-loading the core purpose. Every section adds value, though some details could be tightened for brevity.

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

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

Despite no output schema, the description thoroughly documents response structure (market fields, analysis, evidence, resolver, parent event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Highly complete for a complex tool.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters. The description does not add significant extra meaning beyond the schema, meeting the baseline expectation.

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 researches Polymarket bets by pulling relevant Pipeworx data, with specific input types. It distinguishes itself through its comprehensive fan-out design, making it unique among siblings.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides extensive examples and explains when not to trust results (low confidence, closed markets).

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

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

Adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, returns sorted results, and includes citation URIs. No contradiction with readOnly/readOnly/mutable hints.

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

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

Single paragraph front-loaded with common query examples. Every sentence adds value—covers purpose, usage, behavior, and parameters 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 only 2 parameters, 100% schema coverage, and no output schema, the description fully explains what the tool returns, how data is sourced, and when it is beneficial over alternatives. No gaps.

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

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

Schema coverage is 100%, but description adds crucial meaning: for 'type' it details what data is pulled per entity type, for 'values' it provides examples and ticker conventions. Also explains how results are sorted for queries like 'largest'.

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 side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific query examples like 'compare X and Y'. It distinguishes itself from sequential single-pack lookups.

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

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

Explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Also details specific use cases for type='company' and type='drug', guiding when to use 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: parallel decomposition across 4,552 tools, expected 15-60s response time, return format (findings packet with evidence, gaps, citations), and the fact that it returns empty gaps for topics not in the structured catalog. 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 comprehensive but somewhat lengthy. It is well-structured with critical information front-loaded (account requirement and alternative tool). Every sentence adds value, but it could be slightly more concise without losing clarity. Still, its thoroughness is justified by the tool's complexity.

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

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

Given the simple parameter set and lack of output schema, the description is remarkably complete. It covers purpose, usage constraints, behavioral expectations, return format, timing, and limitations. No important aspect is left unexplained for an AI agent to use 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?

The input schema has 100% coverage with descriptions, but the tool description adds further meaning: it explains the depth enum values (quick=3, standard=5, thorough=8) and clarifies that the question parameter accepts broad/multi-part queries since decomposition is the point. This adds value beyond the schema.

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

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

The description clearly states that deep research performs grounded multi-source research across 1160 structured data sources, distinguishing it from open-web search and sibling tools like ask_pipeworx. It specifies the scope (structured data) and the decomposition 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?

Explicit usage guidance is provided: best for broad/multi-part questions, alternatives for single lookups (ask_pipeworx) and breaking news (ask_pipeworx again). Account requirements and the paid plan for 'thorough' depth are also mentioned, along with a fallback when not signed in.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details: returns top-N relevant tools with full schemas and examples, ready to call directly without second lookup. No contradictions.

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

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

Description is moderately concise and front-loaded with purpose. Could be slightly more structured but every sentence adds value.

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

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

Given 6 parameters, no output schema, and complex discovery task, the description fully explains what is returned (names, descriptions, schemas) and the use case.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds value by noting aliases for 'query' (task, q, description, search).

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 finds tools by describing data or task, using a specific verb ('Find') and resource ('tools'). It distinguishes from siblings by being the discovery tool in a list of domain-specific tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set.' Provides context with examples but lacks when-not-to-use or alternative 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?

The description discloses multiple behavioral traits: the tool fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes that the patents part is sunsetting and will soft-fail. Annotations already indicate read-only, non-destructive, and idempotent behavior, so the description adds useful 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 comprehensive but somewhat verbose (over 200 words). It front-loads example queries and the core purpose effectively. While every sentence adds value, the details about patents and LEI sources could be more succinct. Still, 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 (multi-source aggregation) and the absence of an output schema, the description adequately explains the return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and the patent sunset limitation. It is complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond the schema: it explains that 'type' currently only supports 'company', clarifies that 'value' expects ticker or zero-padded CIK, and reiterates that names are not supported, directing the agent to resolve_entity. This enhances parameter understanding.

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

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

The description explicitly states the tool's purpose: providing a full cross-source profile of a US public company in one call. It uses specific verbs ('profile', 'research', 'tell me about') and distinguishes from sibling tools by noting it should be preferred over chaining single-pack lookups and that names are not supported (use resolve_entity instead).

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

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

The description provides clear when-to-use guidance: when the user asks for a holistic view of a company (lists example queries). It explicitly advises to prefer this tool over chaining other lookups and tells the agent to use resolve_entity if only a name is available. This effectively differentiates usage from alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds contextual reason for deletion (clearing sensitive data) but doesn't disclose additional behavioral traits beyond annotations.

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

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

Two concise sentences. First states purpose, second provides usage context and sibling references. No wasted words.

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

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

Complete for a simple deletion tool: describes action, when to use, and references related tools. No output schema needed.

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 parameter with description 'Memory key to delete', so baseline is 3. Description does not add extra parameter semantics 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 the tool deletes a previously stored memory by key, using strong verb 'Delete' and specific resource. Distinct from siblings like '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 tells when to use: when context is stale, task done, or clearing sensitive data. Also recommends pairing with 'remember' and 'recall' for context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it fetches content and emits markdown, but doesn't go beyond that. No contradictions, but no additional behavioral context like rate limits or authentication.

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

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

Three sentences, each adding value: main purpose, how it works, use cases. No redundant information.

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

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

No output schema, but description states output is a text blob for site-root/llms.txt, which is sufficient for this simple tool. Covers all needed context.

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

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

Schema coverage is 100%, but the description adds examples for the URL parameter and notes the default and max for max_links, providing extra clarity 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 generates an llms.txt file for AI crawlers, with specific actions (fetches, extracts, emits). It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file creation.

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

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

The description explicitly lists useful scenarios (indexing a client's site, drafting for own project, auditing competitor). While it doesn't explicitly say when not to use, the context is clear and covers common 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context (ArcGIS layer) but no further behavioral details beyond what annotations provide. 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?

Single, well-structured sentence with key information front-loaded. No unnecessary words. 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?

Simple tool with one parameter and no output schema. Description fully covers what the tool does and returns. Annotations provide comprehensive behavioral info.

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

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

Schema coverage is 100% with clear description of 'url' parameter. Description does not add extra meaning to the parameter beyond what schema provides (e.g., no examples or constraints). Baseline score of 3 applies.

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

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

Description uses specific verb 'Get' and resource 'ArcGIS Feature/Map Service layer schema', listing exact outputs (fields, geometry type, record count, capabilities) and distinguishing from sibling 'query_layer' which likely queries 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?

Implies usage for retrieving schema given a URL, but does not explicitly state when to use vs alternatives like 'query_layer', or when not to use (e.g., for querying data). Provides minimal 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, covering safety. Description adds return fields but doesn't contradict annotations.

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

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

Two concise sentences, front-loaded with purpose then usage guidance. No wasted words.

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

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

Annotations and schema cover safety. Description lists return fields compensating for missing output schema. Minor gap: structure of 'params' field not detailed.

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

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

Schema covers both parameters 100%. Description mentions return fields but adds no extra meaning for the input parameter include_inactive beyond schema.

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

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

Description clearly states 'List the caller's active subscriptions', specifying verb and resource. It distinguishes from siblings like subscribe and unsubscribe by focusing on listing active subscriptions.

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

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

Explicitly guides to 'review what you're monitoring before adding more or to find an id to cancel', effectively providing when-to-use and implied when-not-to-use.

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

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

Annotations are non-committal (no readOnly, idempotent, etc.), but the description adds critical behavioral info: rate-limited to 5 per identifier per day, free, doesn't count against quota. No contradictions with annotations.

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

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

Single paragraph, front-loaded with purpose, includes key usage details, constraints, and formatting advice. Every sentence adds value; no unnecessary words.

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

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

Given the tool's simplicity (feedback submission, 3 params, no output schema), the description is fully complete. It covers purpose, usage scenarios, parameter expectations, constraints, and context signals like rate limits.

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

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

Schema has 100% coverage with clear descriptions for each parameter (type, context, message). The description adds extra guidance on how to use each type and emphasizes describing issues in terms of tools/packs, which enhances 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: to tell the Pipeworx team about something broken, missing, or needing existence. It lists specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by being a feedback channel rather than a query tool.

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

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

Explicitly provides when to use: for bugs, missing features, data gaps, or praise. Also advises against pasting end-user prompts and describes how to frame feedback in terms of Pipeworx tools/packs. Mentions rate limits and free usage, aiding appropriate invocation.

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

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

Annotations already declare read-only, non-destructive, idempotent, and open world. Description adds caching behavior (5min-1h depending on window) and no-PII claim, which are useful beyond annotations.

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

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

Three sentences with no waste. Front-loaded with purpose, then use cases, then technical details (caching, PII). Efficient and well-structured.

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

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

For a simple 1-param tool with no output schema and rich annotations, the description fully covers what the tool does, how to use the parameter, behavioral traits, and appropriateness. No gaps.

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

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

Schema coverage is 100% with one parameter. Description adds interpretation: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This 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?

Specifies verb 'returns' and resource 'top tools, top packs, and total call volume' over a window. Clearly distinguishes from sibling tools like ask_pipeworx or search_datasets by focusing on trending/aggregate data.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical choice, aligning use case). Does not explicitly state when not to use, but the specialized purpose makes usage context 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?

Discloses internal behaviors beyond annotations: walks child markets, performs Jaccard similarity filtering, filters placeholders, handles fill check via internal call. Annotations already indicate idempotent and read-only, and description adds rich behavioral context without contradiction.

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

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

Front-loaded with key information and well-structured with mode-specific paragraphs. Slightly verbose with technical details, but every sentence contributes value. Could be tightened without losing clarity.

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

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

Comprehensive given no output schema: explains response structure including nested objects (opportunities, partition_check). Covers edge cases (low similarity, placeholder filtering), trade signals, and references sibling tool. No missing context for correct 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?

Adds significant meaning beyond input schema: explains event slug examples, full URL acceptance, and the semantic purpose of topic as a seed question. Schema coverage is 100% but description greatly enhances understanding.

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

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

The description clearly states the tool finds arbitrage opportunities using monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for specific market, topic for cross-event, making it distinct from sibling tools like polymarket_edges.

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

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

Explicitly describes when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises when not to trade via fill check and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant behavioral detail: caching at KV level keyed on knobs, response diagnostics for empty segments, Fed bets exclusion rationale, and model family internals (e.g., lognormal barrier, GDELT ratio). 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 lengthy (~400 words) but well-structured with sections and front-loaded purpose. Each section adds necessary detail for complex model families and knobs. Could be slightly more concise, but structure is 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?

No output schema provided, but description fully explains response structure (by_segment, fed_candidates, _diagnostics) and fields in each opportunity (edge_pp_net, kelly_fraction, etc.), making it complete for agent invocation without needing external documentation.

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. Description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in context of the overall logic, enhancing understanding beyond 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?

Clearly states verb 'scan' and 'return' with resource 'Polymarket markets' and specific outcome 'opportunities where Pipeworx data disagrees with market price'. Describes purpose for 'what should I bet on today' and distinguishes from siblings by detailing three model families.

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 built for 'what should I bet on today' and agents can discover without paging. Describes three segments and when each applies, plus tradeable-edge knobs for filtering. However, does not explicitly state when not to use or list alternatives among siblings.

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

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

Annotations already declare safe read-only idempotent operation. Description adds limits (60-day TTL), dependency on snapshotting, and that decay uses daily closes (not intraday). 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?

Dense but efficient; front-loads purpose then details response and limits. Slightly verbose but each sentence adds value.

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

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

No output schema, but description fully explains return structure (tracked, expired, snapshot_dates) and their fields. Also covers limits and dependencies.

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% but description adds defaults, clamp ranges, and interpretation of window values (24hr, 1wk, 1mo), adding 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?

Description clearly states the tool provides 'edge persistence and decay telemetry' answering a specific question. Distinguishes from siblings by focusing on time-series of edges.

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

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

Implied usage context (assessing edge age and decay) but no explicit when-to-use or when-not-to-use vs. alternatives like polymarket_edges.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds valuable behavioral details: walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, and forced_directional_risk. 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 detailed but well-structured with clear sections for single-market and basket modes, and usage guidance at the end. It is front-loaded with the core purpose. While verbose, every sentence provides necessary context, justifying 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 the tool's complexity (two modes, multiple return fields, no output schema), the description is comprehensive. It enumerates return fields for both modes, explains the clamp on size_usd, and mentions forced_directional_risk. Some minor details like error handling could be added, but overall it's 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% with all 4 parameters documented. The description adds meaning by explaining the dual modes, default values, and interpretation differences for size_usd between modes. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-check. The two modes (single-market and basket) are clearly described.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risk of partial basket fills converting an arb into an unhedged directional position, providing clear context for usage.

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, idempotent, non-destructive. Description adds detailed behavioral info: two modes, compatibility_warning conditions, temporal alignment, skipped counters. 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?

Well-structured, front-loaded with purpose and modes. Each section adds value, but slightly verbose with extensive safety field explanations. Could be tightened without losing information.

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

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

No output schema, but description thoroughly explains return values (leg-by-leg prices, matched spreads, safety fields like compatibility_warning, temporal_alignment, skipped counters). All necessary context for agent to use 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 has 100% coverage with descriptions for all 3 parameters. Description adds context about modes and interaction between topic and explicit tickers, including override behavior. One point docked because schema already does heavy lifting.

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

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

States the tool computes cross-venue spread between Kalshi and Polymarket. Describes two modes (topic shortcuts and explicit tickers) and clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on same-question spread comparison.

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

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

Explicitly tells when to use (comparing prices across venues for same resolving question) and when not (most pre-mapped topics return compatibility_warning, pre-mapped ≠ tradeable). Provides guidance on interpreting safety fields.

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

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

Annotations already indicate readOnly, idempotent, non-destructive, and open world. The description adds that it returns rows and geometry, which aligns with annotations. No further behavioral details (e.g., rate limits, error handling) are provided, but given annotation richness, the additional context is moderate.

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

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

The description is three sentences: first sentence introduces the tool and lists parameters, second states output, third provides a usage example. Every sentence adds value, and the key information is front-loaded.

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

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

For a query tool with 6 parameters and no output schema, the description covers the core functionality and includes a sample invocation. It lacks details on pagination behavior and geometry format, but is mostly complete given the context.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds 'SQL-like', 'comma-separated', and a sampling example, but these are minor enhancements. The defaults for where and out_fields are restated from the schema, adding limited new meaning.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer with SQL-like parameters. It implicitly differentiates from siblings like search_datasets and layer_info by focusing on data querying, but does not explicitly contrast with them.

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

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

The description provides context about the URL coming from search_datasets and includes a practical sampling tip. However, it does not specify when not to use this tool or compare it to alternatives, which would improve 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 read-only, idempotent, non-destructive. Description adds scope (identifier-based), behavior of omitting key (list all), and pairing with remember/forget. No contradictions, adds useful behavioral context.

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

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

Two sentences plus a contextual note. All sentences are meaningful, no redundancy. Front-loaded with core action.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers purpose, parameter behavior, scope, and sibling relationships. Lacks return format details, but not critical 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 schema description already notes 'omit to list all keys'. Description repeats that without adding new semantics. 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 uses specific verbs ('retrieve', 'list') and resources ('value', 'keys'), and explicitly distinguishes from sibling tools ('remember', 'forget'). Concrete examples (ticker, address, research notes) anchor the purpose.

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

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

Clearly states when to use: 'look up context stored earlier... without re-deriving from scratch'. Mentions pairing with remember/forget and scope. No explicit when-not-to-use, 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's disclosure of the mark_read parameter's side effect (marking events read so next call shows newer ones) adds valuable behavioral context beyond the annotations. It also confirms polling 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 compact (~100 words) and front-loaded with the core purpose. Each sentence contributes unique information: purpose, content, filtering, mark_read behavior, and alternative access. No filler or repetition.

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

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

Given the tool has 5 optional parameters, no output schema, and safety annotations, the description covers the return content (source, citation_uri, raw payload), filtering options, and stateful behavior of mark_read. It does not detail limit behavior, but that is documented in the schema. Overall, it provides sufficient context for an agent to use the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds extra meaning by explaining that setting mark_read to true 'flag[s] returned events read so the next call only shows newer ones,' which clarifies the stateful behavior beyond the schema's simple description. Other parameters (type, since) are mentioned with their filtering role.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the tool's action (pull) and the resource (fired events from subscription feed). It further details what each alert carries (source, citation_uri, raw payload), making the purpose very specific and unambiguous.

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

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

The description provides guidance by stating 'Polls work fine' and mentioning the alternative endpoint at alerts.json for scripts/dashboards. However, it does not explicitly state when not to use this tool or directly compare it to sibling tools like list_subscriptions, though the context implies it is for retrieving alerts, not managing subscriptions.

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

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

Discloses fan-out behavior across multiple sources, fallback mechanism (GDELT→GNews), soft-fail for USPTO due to API sunset, and return structure (changes[] grouped by source, total_changes, citation URIs). Annotations already indicate safe/idempotent read, but description adds significant behavioral context beyond annotations.

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

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

Single dense paragraph, front-loaded with examples, no wasted words. Every sentence provides critical information (purpose, usage, behavior, parameters, return structure, alternatives). Ideal conciseness.

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

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

Given complexity (multiple sources, fallback, soft-fail, no output schema), the description is complete. It covers all input parameters, explains the data sources and fallback, describes the return format, and provides usage guidelines. Agent can correctly select and invoke the tool.

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

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

Schema coverage is 100%, but description adds meaning: explains `since` accepts ISO or relative shorthand, recommends '30d', explains `value` accepts ticker or CIK, and adds context about the fallback chain for the tool's overall behavior. Adds value beyond 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 it's a 'change feed for a company' with specific example queries like 'what's new with X'. It distinguishes from sibling tool entity_profile by explicitly recommending it for static profiles. Very specific verb+resource and differentiation.

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 usage alternatives: 'Use entity_profile instead when you want the static profile'. Also gives example queries and typical monitoring recommendation for `since` parameter ('Use "30d" or "1m" for typical monitoring').

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 by identifier, persistence details (24 hours for anonymous, persistent for authenticated), and that it's a write operation. Consistent with annotations; adds value beyond them.

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

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

Four sentences, front-loaded with purpose, no fluff. Every sentence adds value.

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

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

Complete for a simple key-value store tool: purpose, usage, behavior, related tools all covered. No output schema needed.

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 concrete examples of keys and clarifies value as any text, enhancing understanding.

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

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

Clearly states the tool saves data for reuse across conversations/sessions. Uses specific verb 'Save' and resource 'data', and distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Provides context on persistence (authenticated vs anonymous) and pairs with recall/forget.

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

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

Description adds beyond annotations: mentions internal cascading through several endpoints and replaces 2-3 manual lookups. It specifies return formats for each type, including citation URIs. No contradiction with annotations.

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

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

Description is comprehensive but slightly verbose; every sentence adds value, but could be trimmed slightly. Front-loaded with examples and core statement.

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

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

Given two simple parameters, no output schema, and annotations covering safety/idempotence, the description fully explains behavior, return values, internal cascading, and citation formats. Complete for intended use.

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

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

Schema coverage is 100% and description enriches each parameter with examples and output details (e.g., 'company returns ticker + 10-digit CIK + company_name from SEC EDGAR + citation URI'). Adds meaning not in schema.

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

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

The description clearly states it resolves names to canonical identifiers, with specific examples ('What's the ticker for…') and explicit purpose statement. It distinguishes from sibling tools by saying 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID,' providing strong when-to-use guidance. It also details supported types and their input/output, making context 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 indicate readonly, open world, idempotent, non-destructive behavior. The description adds procedural details: it probes each entity with ai_visibility_check, ranks them, and returns a ranked list with score, confidence, signal density. These go beyond annotations and together provide a clear picture of what the tool does and its safety profile.

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

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

The description is three sentences: first states the action, second explains the mechanism, third gives a concrete use case and expected output. There is no fluff; each sentence earns its place. It is well-structured and easy to parse.

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 thoroughly explains what the tool returns: a ranked list with score, confidence, signal density. It covers the workflow (probing and ranking), input parameters, and use case. Given the tool's moderate complexity, this is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that the first entity in 'entities' is treated as the 'subject' and the rest as competitors, which is not in the schema. This enhances parameter understanding for the agent.

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 'Compare' and resource 'AI visibility across multiple entities'. It specifies the process: probes each entity with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. This differentiates it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies use for side-by-side comparison. While it doesn't explicitly state when not to use or name alternatives, the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradictions.

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

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

Description is detailed but front-loaded with core purpose. Multiple sentences each add value (e.g., ecosystem scope, partial failure handling). Minor redundancy could be trimmed, but overall well-structured for an AI agent.

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

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

No output schema, so description fully explains return values: summary block fields (is_latest, license, bundle sizes, etc.), per-advisory detail, links, and recent alternatives. Also covers edge cases like partial failures and timeouts. Complete for a tool with 2 parameters.

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

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

Schema has 100% coverage for both parameters (package and version). Description adds extra meaning: scoped packages (e.g., '@types/node') are accepted for 'package', and 'version' defaults to latest when omitted. This enhances 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 it is a composite check for npm packages using deps.dev and bundlephobia, specifying the verb 'scan' and resource 'dependency'. It distinguishes from siblings by being specific to npm and composite checks, unlike other tools like 'deep_research' or 'validate_claim'.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also notes that other ecosystems (PyPI, Maven, etc.) are covered by a different tool (deps.dev:version directly), providing clear guidance on 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, openWorldHint, idempotentHint, and destructiveHint. The description adds that this searches a specific geographic scope (City of Peterborough GIS) and returns specific fields, providing context beyond annotations. No contradictions.

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

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

Two sentences with no unnecessary words. Front-loaded with the key action and resource, then provides details on return values and follow-up usage. Efficient and clear.

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

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

For a search tool with 3 parameters and no output schema, the description adequately explains what is returned and how to use the results. It does not explain pagination or limit default, but that is covered in the schema. Lacks explanation of optional org_id parameter, but it is self-explanatory.

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

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

Schema documentation coverage is 100%, so baseline is 3. The description does not add new meaning to parameters beyond what the schema already describes. It mentions keyword search but that is synonymous with the query parameter.

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

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

Description clearly states it searches City of Peterborough GIS datasets by keyword and lists exact return fields (name, summary, record_count, owner/org, Feature Service url). It also differentiates from siblings by specifying that the url can be passed to query_layer or 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?

Explicitly says when to use (search datasets by keyword) and provides guidance on using the result with query_layer/layer_info. However, it does not explicitly state when not to use or compare to similar search tools like search_within.

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 technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging. No contradiction with annotations (readOnly, idempotent, non-destructive). This fully informs the agent of 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?

Three sentences, front-loaded with core purpose, every sentence adds value. No wasted words.

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

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

Given no output schema, the description explains return format (passages with offsets and scores). It also covers technical implementation, truncation, and pairing with other tools. Fully complete for tool complexity.

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

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

Parameter descriptions in the schema already cover meaning, but the description adds value by specifying max chars for 'text', default for 'limit', and clarifying that 'query' is natural language. This extra context justifies above baseline 3.

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

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

The description states clearly that the tool performs semantic search inside a fetched record, using the verb 'search inside' and specifying the resource. It distinguishes itself from siblings like ask_pipeworx_grounded and search_datasets by emphasizing returning passages with offsets and scores.

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 using this tool 'when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. While it provides clear context, 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 indicate a write operation (readOnlyHint=false). The description adds significant behavioral context: returns a subscription id, requires OAuth, details delivery channels with constraints (SMS cap, webhook auto-disable), and type-specific parameters. 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 lengthy but well-structured: starts with purpose, then authentication, then types with examples, then delivery options. Every sentence adds necessary detail; slight verbosity is justified by complexity.

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

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

Given the tool's complexity (multiple types, delivery channels, constraints), the description covers all necessary context: authentication, type-specific parameter examples, delivery options with limitations, and return value (subscription id). No output schema is needed because the return is simple.

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 100% coverage, so the description's parameter info is supplementary. It provides concrete examples for each type and delivery channel, and explains constraints (e.g., SMS must match verified phone, webhook signing). This adds value beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation rather than listing or removal.

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

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

The description provides context on when to use (proactive monitoring), authentication requirements (Pipeworx OAuth account), and notes that anonymous/BYO cannot persist subscriptions. It implicitly contrasts with list_subscriptions, but does not explicitly state when not to use this tool versus 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 safety and idempotency. The description adds valuable detail beyond annotations: it describes the output (category-bucketed examples with tool+argument shapes from a live catalog) and explains how topic parameter affects results. This effectively informs agent behavior without contradicting 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 longer but well-structured with front-loaded common queries. Every sentence adds value (purpose, usage, examples, behavior). Could be slightly trimmed but remains effective.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage timing, parameter behavior, output contents, and distinguishes from siblings. No gaps apparent.

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

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

Description adds meaning beyond the schema by illustrating how the topic parameter selects focus areas and clarifies that omitting it yields a full spread. Schema coverage is 100%, so baseline is 3; extra context raises the score.

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 returns category-bucketed example questions with tool+argument shapes, distinguishing it from other tools by positioning it as an onboarding entry point for exploring Pipeworx capabilities.

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 this tool FIRST when the agent doesn't know what Pipeworx can do, and contrasts with meta-tools by showing how to learn their usage. Also explains parameter usage and full vs. focused 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?

Description adds value beyond annotations by specifying 'deactivated not deleted' and ownership enforcement, while idempotentHint is already annotated.

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

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

Two concise sentences that front-load key actions and constraints, with no unnecessary words.

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

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

For a single-parameter tool with no output schema, the description covers ownership, effect, and relation to sibling tools, making it fully actionable.

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?

Parameter 'id' has 100% schema coverage with a brief description; the tool description provides no additional parameter details, which is adequate for a simple UUID parameter.

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

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

Description clearly states it cancels a subscription by ID, distinguishes from subscribe (opposite) and list_subscriptions, and explains deactivation vs deletion, leaving no ambiguity.

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

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

Explicitly mentions ownership enforcement (only self-cancellation) and points to recent_alerts for history. Does not explicitly list alternatives or when-not-to-use, but context is sufficient.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it returns a verdict, structured form, actual value with citation, and delta, and explains it replaces multiple sequential calls. 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 detailed but each sentence adds value: trigger phrases, usage guidance, domain scope, output format, and efficiency benefit. It is front-loaded and while slightly long, it remains focused.

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

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

Given the simple input schema and comprehensive annotations, the description covers purpose, usage, behavior, and output. It mentions verdict types, structured form, and citation, which is sufficient for an agent to understand the tool's capabilities without an output schema.

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

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

The single parameter 'claim' has a clear description in the input schema with examples. The tool description reinforces this with example queries. Schema description coverage is 100%, so the description complements without redundancy.

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

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

The description clearly states that the tool verifies natural-language claims against authoritative sources, specifically for company-financial claims. It provides multiple example queries and distinguishes itself by replacing 4-6 sequential calls, making its purpose unambiguous.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the domain (company-financial claims). It lacks explicit when-not-to-use or alternatives, but the sibling list is provided and the scope is well-defined.

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