Arcgis Courtenay

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

The description fully aligns with annotations (readOnlyHint, idempotentHint, etc.) and adds crucial behavioral details: it probes LLMs, requires no destructive actions, and explains the cost model (free default, BYO key for Anthropic). 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 compact (4 sentences), front-loaded with the core action, then provides key details (default model, optional API key, return structure, use cases). No redundant sentences.

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

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

Given 4 parameters (1 required), no output schema, and no nested objects, the description covers the main inputs, output shape (per-model plus combined view), and use cases. It misses exact field names in the output but is sufficient for an agent to understand what to expect.

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

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

With 100% schema description coverage, the schema already documents each parameter. The description adds value by explaining the default model and the purpose of _apiKey, as well as the combined use case context. This goes beyond the schema but is not essential for basic usage.

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

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

The description uses a specific verb ('probe') and a clearly defined resource ('LLMs for what they know about a business/brand/product/topic'), with a measurable output ('score 0-100 per model'). It immediately distinguishes this tool from siblings like 'scan_competitor_ai_presence' and 'deep_research'.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs optional Anthropic model with key requirements. While it doesn't explicitly list when NOT to use this tool or name specific alternatives, the context is clear enough 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?

Description adds value beyond annotations: mentions response includes stable citation URIs, one fast call per tier, and works on all tiers. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and description aligns with these.

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

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

Description is front-loaded with key preference statement, but is somewhat lengthy with examples and detailed use-case guidance. Could be slightly trimmed without losing value, but structure is logical.

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

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

Given the tool's simplicity (one required param) and rich annotations, the description is fully adequate: it explains when to use, how it works, and provides practical examples and sibling distinctions.

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 aliases documented. Description adds no further detail beyond 'natural language question'. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the tool routes factual questions to one of many verified sources and returns structured answers with citations. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly instructs to prefer this tool over web search for factual queries, lists trigger phrases ('what is', 'look up'), and provides clear escalation paths to ask_pipeworx_grounded (single hallucination-resistant answer) and deep_research (broad multi-part queries).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: extra LLM call cost, structured refusal reasons (not_in_source, no_tool_match, etc.), evidence extraction, and return format details. No contradictions with annotations.

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

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

The description is well-structured, starting with purpose, then process, usage guidance, and cost trade-off. Each sentence adds value. Slightly verbose in detailing return structure but remains focused. Appropriate length for a complex tool.

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

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

Given the tool's complexity (routing to many sources, extracting answers, structured refusals), the description covers purpose, process, output format, usage scenarios, and cost trade-off. No output schema, but description explains return structure. Good completeness.

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

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

Schema coverage is 100% with descriptions for all 6 parameters (all aliases for 'question'). The description adds minimal value beyond the schema, only mentioning that it accepts natural language. Baseline of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads,' explaining its process (routing, fetching, extracting) and distinguishing it from the sibling 'ask_pipeworx' by being more strict about using only fetched data. This provides a specific verb-resource combination with clear 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims, medical lookups, public statements). Also advises to prefer 'ask_pipeworx for casual lookups,' giving both inclusion and exclusion 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds extensive behavioral context: resolver contract with confidence levels and suggestions, parent event extractor, news field fallbacks, safety short-circuits for low confidence/closed markets, wide spread tradeability notes, and cancellation rule parsing. 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 very long but front-loaded with core purpose. Every sentence adds value, but could benefit from more structured formatting (e.g., bullet points). Still concise relative to the amount of information conveyed.

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 covers response shapes (market, analysis, evidence), resolver contract with match confidence and alternatives, parent event extractor, news fields, and error cases (low confidence, closed markets, wide spreads, cancellation rules). Very thorough for a complex tool.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: explains market_input accepts slug, URL, or question text; depth parameter (quick vs thorough); include_raw (summarized vs full payloads, size implications). Goes well 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 researches a Polymarket bet by pulling Pipeworx data. It gives specific verb+resource and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on comprehensive data gathering. Also provides example queries like 'should I bet on X'.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides classifier examples and fan-out patterns. Does not explicitly state when not to use, but the context is clear enough 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 indicate read-only, idempotent, etc. Description adds context: data sources (SEC EDGAR/XBRL, FAERS), correct handling of fiscal years, sorting by primary metric. 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 paragraph but includes all key details. Could be broken into clearer sections, but it's not overly long and is front-loaded with purpose.

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

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

Despite no output schema, description explains return data (paired data + citation URIs) and sorting. Covers both entity types thoroughly. Slightly more detail on output format would be ideal.

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

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

Schema coverage is 100%. Description adds examples of valid values (tickers/CIKs, drug names) and clarifies special handling of fiscal years, going beyond the schema's basic type 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: side-by-side comparison of 2-5 companies or drugs. It provides example triggers and specifies what data is pulled for each type, distinguishing it from sequential lookups.

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

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

Explicitly advises preferring this tool over sequential single-pack lookups when comparing entities. Also specifies constraints (2-5 entities, types company/drug).

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 extensive behavioral context beyond annotations: parallel execution, output format with evidence/confidence/citations, gap recovery, contradiction scanning, hop field, citation URIs, time estimates, and large record excerpting. Annotations only provide readOnlyHint and openWorldHint; the description enriches transparency.

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

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

The description is comprehensive but lengthy. It front-loads the critical account requirement and alternative tool. Every sentence adds value, but could be slightly more structured with bullet points for ease of scanning. Nonetheless, it earns its length.

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

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

Given no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, citations, gaps, contradictions). It covers all behavioral aspects: depth options, timing, error handling, and iterative hops. No missing critical information for an AI agent to decide usage.

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

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

Even though schema coverage is 100%, the description adds significant meaning: explains depth options (quick/standard/thorough) with facet counts, gap recovery, and contradictions. For the question parameter, it clarifies that broad/multi-part is fine. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: grounded multi-source research across 1293 structured data sources in one call, distinguishing it from ask_pipeworx (single lookup) and open-web search. It provides specific verb+resource and contrasts with sibling tools.

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

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

Explicitly tells when to use this tool (broad/multi-part structured data questions) and when to use alternatives (ask_pipeworx for single lookups or breaking news). Also mentions account requirement: use ask_pipeworx if 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 provide readOnlyHint=true and idempotentHint=true. The description adds that the tool returns schemas and examples ready to call, and accepts multiple aliases. No contradictions. It discloses key 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?

The description is relatively long but well-structured and front-loaded. Every sentence adds value: purpose, usage, domains, output details, and ordering advice. Could be slightly more concise, but no waste.

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 explains the output format clearly (names, descriptions, schemas, examples). It mentions the limit parameter indirectly via schema but not in the description. Overall, context is adequate for a discovery tool.

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

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

Schema coverage is 100% with descriptions. The description adds value by listing aliases (task, q, description, search) and providing example queries. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous domains (SEC filings, FDA drugs, etc.) and explains the output (top-N relevant tools with full schemas). This distinguishes it from sibling tools that perform specific tasks.

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

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

Explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use and implies alternatives.

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

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

Discloses data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), behavior (parallel call, soft-fail for patents, fallback chain), and return fields. Annotations already indicate safe read, but description adds rich behavioral context.

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

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

Front-loaded with examples and key usage note. Each sentence adds unique information. Slightly long but efficient for the detail provided.

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

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

Given no output schema, the description thoroughly lists return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Covers complexity well, with adequate context for siblings.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'type' only supports 'company' for now and 'value' must be ticker or CIK (not names), and recommends resolve_entity if only a name is available.

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 provides a 'full cross-source profile of a US public company in ONE parallel call.' The examples ('Tell me about X', 'research Acme') and the directive to prefer over chaining single-pack lookups distinguish it from 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 says when to use (holistic view requests) and when not (names not supported, must use resolve_entity first). Provides clear alternatives and 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 provide destructiveHint=true and readOnlyHint=false. The description adds context about deleting 'previously stored memory' and use cases, but does not add significant behavioral detail beyond what annotations convey.

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

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

Two sentences, no redundancy. Front-loaded with the action verb 'Delete' and the resource 'memory by key'. 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?

With only one required parameter, no output schema, and ample annotations, the description covers purpose, usage guidance, and pairing with siblings. No gaps identified.

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 the single parameter 'key', so baseline is 3. The description does not add additional meaning beyond what the schema already provides for the 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?

The description clearly states it deletes a memory by key ('Delete a previously stored memory by key'). It distinguishes from siblings 'remember' and 'recall' by explicitly mentioning pairing, and the action is specific to deletion.

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

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

Provides explicit when-to-use conditions: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', implying appropriate alternatives.

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

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

Annotations declare read-only, idempotent, non-destructive behavior. The description adds that the tool fetches pages and extracts content, which are key behavioral traits beyond the 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?

The description is concise (three sentences) and front-loaded with the primary purpose. Every sentence adds value: purpose, process, and use cases. No wasted words.

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

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

Despite lacking an output schema, the description clearly explains the output format ('single text blob ready to drop at site-root/llms.txt'). This is sufficient for an agent to understand the result.

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

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

Schema coverage is 100% with both parameters documented. The description does not add new semantics beyond the schema; it restates the default for max_links (25) which is already in the schema.

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

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

The description clearly states the tool generates an llms.txt file for any URL, specifying the verb ('Generate'), resource ('llms.txt file'), and target audience ('AI crawlers'). It differentiates from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation.

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 concrete use cases ('getting a client's site indexed', 'drafting for your own project', 'auditing a competitor'), giving clear context for when to use. However, it does not explicitly state when not to use or compare to 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 non-destructive. The description adds behavioral context by listing the specific schema information returned (fields, geometry type, record count, capabilities), which is beyond annotation coverage.

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

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

The description is a single, well-structured sentence with no wasted words. It front-loads the purpose and specifies exact outputs.

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

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

Given one parameter, no output schema, and comprehensive annotations, the description covers the return values (fields, geometry type, record count, capabilities) adequately. No gaps identified.

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 the single parameter 'url' described as 'Feature/Map Service layer url, e.g. '.../FeatureServer/0'.'. The description repeats this but adds no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (Get), the resource (ArcGIS Feature/Map Service layer's schema), and the specific outputs (fields, geometry type, record count, capabilities). It distinguishes from siblings like query_layer which is for querying 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?

Usage is implied (retrieving schema for a layer URL), but there is no explicit guidance on when to use this tool versus alternatives (e.g., query_layer) or when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds clarity on return fields and the effect of the include_inactive parameter, but does not introduce 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: first defines purpose and output, second provides usage guidance. No redundant information, perfectly front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage. No additional context 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 coverage is 100% and the description does not add further meaning to the parameter beyond the schema's own description. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and specifies the returned fields. It distinguishes from siblings subscribe and unsubscribe.

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

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

Explicitly guides when to use: 'to review what you're monitoring before adding more or to find an id to cancel', which directly informs agent decision-making against 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?

Beyond annotations (which are mostly false), the description discloses rate limits (5 per identifier per day), free usage, and that feedback is read daily and influences roadmap. 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 compact yet comprehensive: it states purpose, use cases, formatting rules, rate limits, and team response in a well-organized paragraph. Every sentence contributes meaning without redundancy.

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

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

For a feedback tool with no output schema, the description covers all necessary aspects: what it's for, how to use it, constraints, and what happens afterwards. The tool is simple and the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' enum in words, reinforcing the message length limit (1-2 sentences, 2000 chars), and clarifying the context parameter's optional nature. This extra guidance raises the score above baseline.

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

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

The description uses specific verbs like 'tell', 'broken, missing, or needs to exist' and clearly distinguishes the tool as the feedback mechanism. It explicitly lists feedback types (bug, feature, data_gap, praise), making the purpose unambiguous compared to sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit when-to-use scenarios for each feedback type, advises against pasting end-user prompts, and mentions rate limits and quota. This leaves no ambiguity about proper 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, and non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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 concise (3 main sentences plus bullet list), front-loaded with the core function, and every sentence contributes 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?

For a simple read-only tool with one parameter, the description adequately covers what is returned (top tools, packs, volume) and caching. With no output schema, it provides sufficient context for the agent to understand the result.

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

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

Schema coverage is 100% and the parameter description in the schema already explains window options clearly. The tool description does not add further parameter-specific meaning beyond what the schema provides.

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

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

The description clearly states the tool returns trending tools, packs, and call volumes over a window. The verb 'returns' and resource 'trending data' are specific, differentiating it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Three bullet-point use cases explicitly describe when to use the tool (e.g., discovering hot data sources). However, it does not mention when not to use it or suggest alternatives, which would make it stronger.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description confirms and expands on this by detailing monotonicity violations, partition-sum checks, fill check with live CLOB depth, and response structure. It adds significant behavioral context beyond annotations without contradiction.

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

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

The description is information-dense yet well-structured, using headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize details. Every sentence adds value, front-loading the core purpose and then detailing each mode efficiently.

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

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

With no output schema, the description fully details the return structure (opportunities[], partition_check) and explains edge cases (placeholder filter, low similarity, fill check). It provides complete guidance for correct usage across all modes.

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% description coverage (baseline 3), but the description goes far beyond: it explains the exact use cases for event and topic parameters, provides acceptable value examples, and describes behavior of each mode including semantic anchor and partition filter effects.

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

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

The description specifies the tool's purpose with a clear verb+resource ('Find arbitrage opportunities on Polymarket') and distinguishes between three modes (trending scan, event, topic) with specific examples. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains constraints (semantic anchor, partition filter) and recommends an alternative tool for custom sizing ('use polymarket_fill_risk').

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 complemented by extensive description of caching, response structure, model details, and edge filters. No contradictions; all behavioral traits are disclosed.

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

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

The description is verbose with technical model details. While structured into segments, it could be more concise to improve agent parsing efficiency.

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 complexity (9 parameters, no output schema), the description fully explains response structure, model families, diagnostics, and edge cases (e.g., Fed bets, caching). No gaps found.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds context on how knobs affect opportunity selection but does not significantly enhance 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?

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings by focusing on edge discovery with multiple model families, not just arbitration or tracking.

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

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

The description implies usage for daily bet discovery with 'what should I bet on today' and details three model families. It does not explicitly state when not to use or list alternatives, but the sibling tools are available for specific scenarios.

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 details the response structure (tracked[], expired[], snapshot_dates[]) and limitations (TTL, snapshot start, daily close data). This adds significant context beyond the annotations (readOnly, idempotent, etc.), which already indicate safe behavior. There is no contradiction with annotations.

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

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

The description is well-structured: it starts with the core purpose, then details the response format, and ends with limitations. While somewhat lengthy, every sentence adds value and there is no redundancy. It is concise yet comprehensive.

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

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

Given the absence of an output schema, the description fully covers the return fields (tracked, expired, snapshot_dates with their subfields) and limitations. It leaves no critical gaps for an agent to understand what the tool returns and its constraints.

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

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

Both parameters are fully described in the input schema (100% coverage). The description repeats the schema's 'days' and 'window' definitions with minor clarifications (e.g., max 30). It does not add substantial new meaning beyond what the schema already provides, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers') and defines the resource ('edge persistence and decay telemetry'). It distinguishes itself from siblings like 'polymarket_edges' which probably generates the snapshots, and other prediction market tools.

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

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

The description provides clear context on when to use the tool: to see how long an edge has existed and if it's shrinking, contrasting fresh vs old edges. It does not explicitly name alternative tools for when not to use it, but the context is sufficiently clear for an AI agent to infer appropriate 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 indicate read-only, idempotent, not destructive. Description adds behavioral details: walks order book ladder, checks all legs in basket, outputs thin_legs and forced_directional_risk, warns about partial fills. 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 with modes, required arguments, return fields. Every sentence adds value, though slightly verbose. Could be trimmed without loss of essential info.

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

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

Despite no output schema, description comprehensively explains return fields (verdict, thin_legs, forced_directional_risk, etc.) for both modes. Sufficient for an agent to understand tool's behavior and risks.

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

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

Schema coverage is 100%. Description adds context beyond schema: default behavior for side in basket mode, interpretation of size_usd for buys vs sells and basket notional meaning, clamp ranges.

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 is a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. Distinguishes single-market and basket modes with explicit return fields, differentiating from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why partial basket fills lead to unhedged directional risk.

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 non-destructive. Description adds extensive behavioral context: two modes, safety fields (compatibility_warning logic, temporal_alignment, skipped counters), and conditions under which spreads are meaningful. 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 fairly long (~300 words) but well-structured with clear sections (MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, though some phrases could be tightened. Good use of bold and bullet points in concept.

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

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

Despite lacking an output schema, the description fully explains response fields (leg prices, spreads, compatibility_warning, temporal_alignment, skipped counters). Covers edge cases and domain-specific reasoning, making the tool's behavior and outputs clear.

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 each parameter. Description adds value by explaining mode semantics (topic vs explicit), providing the full list of topic shortcuts, and clarifying override behavior. Slightly redundant with schema but useful context.

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

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

Description clearly states it's a cross-venue spread tool between Kalshi and Polymarket for the same resolving question. Details two modes (topic shortcuts and explicit tickers) and response contents. Distinguishes from sibling tools like polymarket_arbitrage by its specific focus on spread calculation across venues.

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 warnings about when spreads are invalid (compatibility_warning cases, temporal misalignment). Notes that pre-mapped topics often yield warnings. However, does not explicitly compare to alternative tools like polymarket_arbitrage for when to use this over other options.

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 the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it returns 'attribute rows (and geometry)', specifies the SQL-like query language, and sets parameter constraints (e.g., limit 1-2000). These details go beyond structured annotations.

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

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

The description is extremely concise with two sentences. The first sentence covers purpose and key parameters; the second provides a practical usage example. Every word is necessary, and the structure is front-loaded with essential information.

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

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

Given the tool's complexity (6 parameters, 1 required, no output schema), the description adequately covers the query mechanism, parameter roles, and a sample call. It lacks details on error handling or geometry format, but for a data retrieval tool this is sufficient.

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

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

With 100% schema coverage, a baseline of 3 is appropriate. The description adds semantic value by summarizing the SQL-like nature of 'where', 'out_fields', 'order_by', and providing usage conventions like comma-separated values and default values. This enriches 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 starts with a specific verb ('Query') and resource ('ArcGIS Feature Service / Map Service layer by its url'), clearly distinguishing from sibling tools like search_datasets (which finds layers) and layer_info (metadata). It precisely communicates the tool's action and scope.

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

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

The description provides explicit usage hints such as 'Use where="1=1" + out_fields="*" to sample.' and references the source of the URL ('from search_datasets'). While it doesn't explicitly state when not to use it or point to alternatives, the context and sibling tools imply appropriate boundaries.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping info (by identifier) and dual behavior (retrieve vs list). 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 front-loaded with main action, followed by examples, scoping, and pairing. 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?

Covers purpose, usage, scoping, and sibling relations. No output schema, but return format is implied by 'value'. Could mention return type, but still complete given simplicity.

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

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

Schema coverage is 100% and description reinforces the parameter's meaning (omit to list all keys). Does not add additional 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 actions: retrieve a stored value or list all keys. Distinguishes from siblings by mentioning remember and forget as paired tools.

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

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

Provides explicit when-to-use examples (look up context, user's target ticker, etc.) and pairs with remember/forget for alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context: explains that the feed is persisted, that 'mark_read' flags events for future calls, and that polling works fine. This is valuable behavioral info beyond the annotations.

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

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

The description is four sentences, front-loaded with purpose, and each sentence adds value. No redundancy or fluff.

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

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

Given no output schema, the description explains what fields are returned (source, citation_uri, raw payload). It covers filtering, pagination (limit), and alternative access. For a read-only tool with comprehensive annotations, this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining the effect of parameters in context (e.g., 'Filter by type (e.g. "sec_8k")', 'Set mark_read:true to flag returned events read so the next call only shows newer ones'). This goes beyond the schema's brief 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 starts with a specific verb ('Pull fired events') and resource ('from your subscription feed'), clearly stating the tool's purpose. It distinguishes itself from siblings like 'list_subscriptions' and 'query_layer' by focusing on recent alerts from a persisted feed.

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

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

The description explains when to use the tool (to get recent alerts, filter by type and time, mark as read) and mentions an alternative endpoint for scripts/dashboards ('GET registry.pipeworx.io/alerts.json'). It could be improved by explicitly stating when not to use this tool, but context is clear.

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

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

Discloses fan-out to multiple sources, GDELT→GNews fallback on rate-limits/5xx, USPTO soft-fail until reactivation, and structured return format. Adds value beyond annotations which already indicate read-only, idempotent, non-destructive.

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 example queries, but the description is dense with multiple details in one paragraph. Still efficient and no wasted sentences.

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

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

Complete for a complex tool: covers data sources, fallback, parameter formats, return structure (grouped changes, total_changes, citation URIs), and alternative tool. No output schema required because return is described.

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 with examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m'. Also clarifies 'value' accepts ticker or CIK.

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

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

The description clearly states the tool returns a change feed for a company from SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes from sibling tool 'entity_profile' and provides example queries like 'What's new with X'.

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 this tool vs. 'entity_profile' ('Use entity_profile instead when you want the static profile'). Also describes when to use (e.g., 'latest on Y') and fallback behavior (GDELT→GNews).

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

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

Annotations already provide idempotentHint=true (safe to retry) and destructiveHint=false. The description adds valuable context: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond annotations without contradiction.

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

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

The description is four sentences, front-loaded with purpose, and every sentence adds value. No redundant or extraneous information.

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

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

Given the tool's simplicity (two required string parameters, no output schema), the description fully covers purpose, usage, behavioral traits, and pairing with related tools. It leaves no important gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples of typical keys (e.g., 'subject_property', 'target_ticker') and clarifies that value can be any text, which supplements the schema and guides the agent on usage.

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

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

The description clearly states the verb ('save'), resource ('data the agent will need to reuse later'), and scope ('across this conversation or across sessions'). It distinguishes from sibling tools like 'recall' and 'forget' by explicitly mentioning them as pairs.

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 usage context: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions paired tools ('recall', 'forget') but does not explicitly state when not to use it or list alternatives beyond these.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds substantial behavioral context: it cascades through multiple endpoints internally, returns specific fields per type (ticker+CIK for companies, RxCUI for drugs), and includes citation URIs. No contradictions with annotations.

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

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

The description is well-structured with two paragraphs and front-loaded examples. Every sentence adds value, though it could be slightly shorter 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?

For a tool with no output schema, the description comprehensively covers inputs, behavior, and expected outputs for both entity types. It explains internal cascading and the value proposition (replaces 2-3 manual lookups). Complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, but the description goes beyond: it explains the 'type' enum values in detail, provides examples for 'value' (AAPL, 0000320193, ozempic), and clarifies auto-disambiguation for company names. This adds significant 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 begins with concrete user queries like 'What's the ticker for…' and clearly states the tool resolves a name to a canonical identifier. It distinguishes itself from siblings like compare_entities and entity_profile by focusing on identifier lookup.

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 FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. While it doesn't explicitly say when not to use it, the context of sibling tools (like compare_entities) implies alternatives.

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

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

The description adds behavioral context beyond the annotations: it internally calls ai_visibility_check, returns a ranked list, and explains parameter-driven behavior (models, API key). The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which the description does not contradict. A small gap: it does not mention that the tool is idempotent or read-only, but annotations cover that.

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 fluff. The first sentence states the core action, the second explains internal process, the third gives a concrete use case. Every sentence is informative and earns its place. Front-loaded with the main purpose.

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

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

Given no output schema, the description adequately describes the return format: ranked list with score, confidence, and signal density per entity. It also explains the internal mechanism (probing ai_visibility_check), parameter roles, and the use case. No gaps for a tool of this complexity.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal new meaning (e.g., 'first entry treated as the subject') but mostly reinforces the schema. For example, the schema already states the first entity is the subject. Therefore, improvement over schema is marginal, meeting the baseline of 3 for high coverage.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It explicitly distinguishes this from single-entity checks and gives an example use case ('does Claude know about us as well as our competitors?'). The verb 'compare' and resource 'AI presence' are 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 explains the tool is useful for competitive AI-marketing audits, indicating when to use it. It implies the sibling tool ai_visibility_check for single-entity queries. However, it does not explicitly state when not to use this tool or list alternatives beyond the implied single-entity check, which would make it a 5.

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

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

Beyond annotations (readOnlyHint, etc.), description discloses partial failure handling ('degrade gracefully'), known delays ('bundlephobia's first measurement on a new version can take 5-30s'), and details of error reporting ('sources_failed will list it'). 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 dense but efficient; every sentence contributes critical info. Front-loaded with core purpose, then detailed behavior and constraints. Slightly long but 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 no output schema, description comprehensively lists return fields, error handling, limitations, and ecosystem scope. It fully addresses what an agent needs to decide invocation and interpret results.

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

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

Schema coverage is 100%, so baseline 3 applies. Description adds marginal value by noting scoped packages are accepted and version defaults, but doesn't elaborate beyond schema.

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

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

The description clearly states the tool performs a composite check for npm packages, aggregating data from deps.dev and bundlephobia. It uses specific verbs ('scan', 'fans out') and identifies the resource (npm packages). The detailed list of returned data distinguishes it from sibling tools.

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

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

Explicitly states when to use (when agent asks about safety, popularity, size) and what queries it addresses. It also specifies ecosystem limitations ('NPM ecosystem only in v1') and points to alternative tools for other ecosystems ('deps.dev:version').

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

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

Description aligns with annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint false). It adds useful behavioral context about the return structure (name, summary, record_count, owner/org, url) and usage flow, going beyond what annotations provide.

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

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

Two sentences, no fluff. Front-loaded with purpose, includes actionable guidance. Every word earns its place.

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

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

For a search tool with 3 parameters (all described in schema) and no output schema, the description adequately covers purpose, usage, and return fields. Missing details about specific return field formats, but overall 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%, so baseline is 3. Description mentions 'by keyword' but does not add new semantic information beyond the parameter descriptions already present in the schema.

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

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

Description clearly states the action (search by keyword) and the specific resource (City of Courtenay GIS open geospatial datasets). It also distinguishes the tool by mentioning the returned Feature Service url and directing to query_layer/layer_info, differentiating it from sibling tools.

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

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

Provides clear context on when to use the tool (to find datasets by keyword) and what to do with the result (pass url to query_layer/layer_info). Does not explicitly state when not to use, but the guidance is sufficient given sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds behavioral details: uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flagging, and offsets for verification. Goes well beyond annotations.

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

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

The description is a single dense paragraph that efficiently conveys key information. It is front-loaded and every sentence adds value, but slight restructuring could improve readability.

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

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

Despite no output schema, the description thoroughly explains the return format (passages with offsets and scores), algorithm, limitations (200K cap, truncation), and pairing with other tools. Completely adequate for an agent to use effectively.

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

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

Schema coverage is 100%, and description adds value by explaining the purpose of each parameter, providing example queries, and clarifying the text parameter's max length. Enhances 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?

The description clearly states it performs semantic search inside a fetched record, specifies inputs (text and query) and outputs (top-N passages with character offsets and similarity scores), and distinguishes itself from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt, and describes pairing with ask_pipeworx_grounded. Provides clear when-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, delivery limits (10/day cap for SMS), webhook signing secret, auto-disable after 10 failures. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, etc.).

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

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

The description is well-structured with two paragraphs, front-loaded purpose, and specific details. Every sentence adds value, though it could be slightly more concise; still efficient for the complexity.

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

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

The description covers parameters fully (100% schema coverage) and describes return behavior (subscription id, webhook_secret). Missing output schema but for a creation tool, this is acceptable. No major 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 the description adds detailed examples for each type, constraints (phone verification, email pattern, webhook HTTPS only), and explains the delivery object fields in depth, providing meaning beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists supported types and delivery channels, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description explicitly states the requirement for a Pipeworx OAuth account and provides specific examples per type. While it doesn't explicitly state when not to use it, the context of sibling tools implies alternatives for querying or listing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the output structure (category-bucketed examples with exact tool+argument shapes) and the optional topic parameter's effect, going beyond static annotations.

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

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

The description is moderately concise, front-loaded with alternative user queries, and structured with parentheses for categories. While it is somewhat long, every sentence earns its place by explaining purpose, behavior, and usage.

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

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

Given the tool has only one optional parameter, no output schema, and rich annotations, the description covers all necessary aspects: when to use, what it returns, parameter options, and relationship to other tools. It is complete for its intended onboarding function.

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

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

Schema coverage is 100% with a clear description for the 'topic' parameter. The description adds semantic value by listing example values (finance, pharma, etc.) and clarifying that omitting the parameter gives a full cross-category spread, which the schema's description does not fully capture.

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 like 'returns category-bucketed example questions' and clearly identifies the resource: the onboarding entry point for an agent that just connected. It distinguishes itself from siblings by being the first tool to use when unfamiliar with Pipeworx's 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 states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. While it doesn't explicitly list when not to use, the context is clear that it's for onboarding.

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 (destructiveHint=false, idempotentHint=true), the description adds critical behavioral details: ownership enforcement, deactivation vs deletion, and preservation of historical events. No contradictions with annotations.

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

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

Three concise sentences with no redundancy. The key action and constraints are front-loaded, and 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?

For a simple tool with one parameter and no output schema, the description is fully complete: it explains the action, constraint, outcome, and how to access related data.

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% for the single parameter 'id', which already explains its source. The description adds context about ownership but does not further elaborate on parameter semantics beyond what the schema provides.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id'. It differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description explicitly says 'you can only cancel your own subscriptions', providing a clear usage constraint. It also explains the outcome (deactivation, not deletion) and how historical data remains accessible via another tool, though it does not explicitly state when not to use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: mentions data source (SEC EDGAR + XBRL), return verdict types, and that it replaces multiple calls. 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 dense and well-structured, starting with trigger phrases then general usage and specifics. It contains valuable information in each sentence, though slightly verbose for a single-parameter tool.

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

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

The description fully covers the tool's behavior: input (natural-language claim), scope (company-financial), data source, return types (verdict, structured form, actual value, citation, delta). Despite lacking an output schema, the description is sufficiently complete 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?

Schema description coverage is 100% with a clear description of the 'claim' parameter. The description reinforces the natural-language nature but doesn't add significant new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides a specific verb ('validate') and resource ('claim'), and distinguishes itself from sibling tools by noting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of claim types (company-financial) and return types. While it doesn't explicitly state when not to use, the context from sibling names implies other tools for different tasks.

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