Arcgis Fallschurch

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

Annotations already cover readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower. The description adds meaningful behavioral context: passing `_apiKey` triggers direct paid calls to Anthropic ('you pay Anthropic directly'), and it discloses the return structure per model. No contradiction with annotations.

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

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

Three concise sentences: the first states purpose, the second covers defaults and key configuration, the third lists use cases and return format. Every sentence adds value, no fluff, and the description is front-loaded with the core action.

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

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

With 4 parameters and no output schema, the description compensates by detailing the return structure (per-model {score, confidence, signals, raw_response} + combined view) and clarifying cost implications. It could note error conditions (e.g., invalid model names), but for a read-only probe tool it is sufficiently 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 semantics beyond the schema by explaining that the default model is Workers AI Llama-3.3-70b (free) and that `_apiKey` is optional but required for Anthropic calls, with a direct pass-through to api.anthropic.com. This enriches the parameter 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 uses a specific verb ('Probe') and states exactly what it does: query one or more LLMs about a business/brand/product/topic and score visibility from 0-100. It clearly distinguishes itself from siblings like ask_pipeworx by focusing on multi-model visibility scoring rather than a single Q&A tool.

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

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

The description provides clear contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` (to include Anthropic) and the default model behavior. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of 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?

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context on the tool's internal routing across 5,462 tools, its speed ('one fast call'), tier availability, and the return of stable citation URIs. This goes well beyond the annotations, though it does not cover potential error modes or rate limits.

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

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

The description is longer than average but every sentence provides actionable guidance, including examples and alternatives. It front-loads the key message ('PREFER OVER WEB SEARCH') and structures use cases clearly. It could be tightened slightly, but remains efficient and well-organized.

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

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

Even without an output schema, the description fully explains what the tool returns (structured answer with citations), when to use it, and how it differs from alternatives. It provides a rich set of examples and covers fallback behavior for grounding and deep research, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides examples and lists aliases, but these are already present in the schema. It does not add new semantics about the 'question' parameter beyond what the schema documents, maintaining the baseline.

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

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

The description clearly states the tool's function: answering factual questions about real-world entities, events, and numbers by routing to verified sources and returning structured answers with citation URIs. It also distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by explicitly naming them as alternatives for different use cases.

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

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

The description gives explicit when-to-use guidance: prefer over web search, start here for most questions, use for specific query types like 'what is' or 'look up', and provides step-up instructions for when to use ask_pipeworx_grounded or deep_research. It also addresses edge cases like breaking news.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: candidate routing may be active under test, currently matches stable exactly, and it is a full working router (not a fallback). It also discloses the comparison against stable for merge decisions, going beyond the annotations without contradiction.

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

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

The description is front-loaded with the core purpose and packs in critical details (identical tools, current status, usage, fallback). It is somewhat repetitive (e.g., stating 'identical' and 'matches exactly'), but each sentence contributes to explaining the experimental nature. A slightly tighter edit would be possible, but overall 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?

For a beta router tool, the description covers the current state (no active candidate), the relationship to the stable ask_pipeworx, usage guidance, and response shape via 'same response shape.' It does not explicitly describe return values, but since it is identical to ask_pipeworx, that is sufficient context. The tool is complex, and the description provides enough for effective use.

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

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

Schema description coverage is 100%, with all 6 parameters being aliases for 'question' and fully documented. The description adds no parameter-specific information, which is acceptable because the schema already carries the full semantic load. Baseline 3 applies.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,462 tools and response shape. It distinguishes itself from the stable sibling by explicitly framing it as the experimental edge with candidate routing improvements. The purpose is unambiguous: ask questions via the router, with an experimental twist.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, providing context for why you might choose beta. However, it does not explicitly mention exclusions or alternatives like ask_pipeworx_grounded, leaving a minor gap.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the refusal mechanism with specific refusal_reason values, the return shape, and the extra LLM call cost. It also clarifies the extraction is limited to the tool result content, adding significant behavioral context not available from annotations. No contradiction exists.

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 every sentence serves a purpose: mechanism, return format, refusal reasons, usage context, and cost comparison. It is front-loaded with the core purpose and structured logically, with no filler or redundant content.

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

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

Despite lacking an output schema, the description fully documents both success and refusal return objects, explicitly lists refusal_reason values, explains the routing relationship with ask_pipeworx, and provides clear usage scenarios. This covers all operational aspects an agent needs for selection and invocation.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description itself adds no additional parameter-specific meaning, so per the rubric the baseline 3 applies. The schema already explains the aliases and the natural-language input.

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 is a 'Hallucination-resistant answer mode for high-stakes reads' that routes like ask_pipeworx, fetches data, and extracts answers using only tool results. It explicitly differentiates from the sibling ask_pipeworx by its grounded extraction and refusal mechanism, leaving no ambiguity about what it does.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and explains the cost tradeoff, giving clear when-to-use vs when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, providing a safe read-only profile. The description goes far beyond this by disclosing edge-case behaviors: the resolver contract with match confidence levels and alternatives, blocking statuses like 'low_confidence_match' and 'market_closed_or_inactive', cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.), news fallback handling (GDELT 429s), and the warning when market moves comparable to model edge. This is rich behavioral context that directly helps an agent avoid misusing results.

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

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

The description is long but well-structured with clear section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the primary purpose. Every sentence adds operational detail—especially good are the concrete fan-out examples and cancellation-rule risks. It is slightly verbose in places (e.g., the extended discussion of closed-market behavior), but given the tool's complexity, the length is justified and not wasteful.

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

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

Despite having no output schema, the description thoroughly documents what the agent can expect: result.market fields, result.analysis fields, result.evidence keying, resolver match confidence and alternatives, parent_event extraction, news fallback fields, and safety statuses. It also covers edge cases (illiquid wide-spread, closed markets, cancellation rules) and includes a caution about resolution-rule risk. This is a complete operational manual 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 description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains that 'market' accepts slug/URL/question text (reinforcing the schema but with examples), describes what 'quick' vs 'thorough' depth actually entails (2-3 sources vs full fan-out), and details the size implications and use cases for 'include_raw' (keeping responses under ~20KB vs 50KB-500KB for recomputation). This elevates the score above baseline, though the schema already documents the core semantics.

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 opens with a specific verb+resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the tool's behavior (resolves, classifies, fans out) and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on bet research rather than edge detection or arbitrage.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly states when to use the tool. However, it does not explicitly mention alternative tools or when NOT to use it (e.g., for pure arbitrage), so it misses the full 'when-not/alternatives' bar for 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?

Annotations already declare readOnlyHint and idempotentHint, so the description's value-added behavior includes data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and citation URIs in responses. This far exceeds the safety profile from annotations.

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

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

The description is moderately long but front-loaded with user queries and core function. Every sentence contributes unique information, from efficiency gains ('Replaces 8–15 sequential lookups') to output details ('paired data + pipeworx:// citation URIs'), with no filler.

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 no output schema, the description compensates by explaining return content (paired data, citation URIs), sorting behavior, and data source nuances. It also covers both entity types and handles off-calendar fiscal years, making it complete for an agent to understand expected 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 covers both parameters with descriptions, but the tool description adds significant meaning: it explains what 'type=company' pulls (revenue, net income, cash, long-term debt from 10-K) and what 'type=drug' pulls (adverse-event counts, FDA approvals, trials). It also clarifies values format (tickers/CIKs vs names) 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 performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, with explicit example queries like 'X vs Y' and 'rank these companies'. It distinguishes from siblings by emphasizing it replaces sequential single-pack lookups and should be preferred for comparisons.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also breaks down behavior for company vs drug types, implying single-entity tasks should use other tools, though no sibling names are mentioned.

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 substantial behavioral context beyond annotations: account/paid-plan requirements, parallel decomposition, gap[] and contradictions[] behavior, no-invention guarantee, semantic excerpting, latency expectations, and citation fetchability. There is no contradiction with the readOnly/openWorld/idempotent/destructive 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?

Though long, the description is extremely dense and every sentence adds crucial operational detail. It is front-loaded with the account requirement and fallback, then systematically covers behavior, limitations, and return packet contents. No filler or redundancy.

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

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

With no output schema, the description fully explains what the tool returns: findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop field. It also covers likely failure modes (current-news topics returning mostly empty gaps[]), latency, and citation resolvability, making it complete for agent use.

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

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

Schema coverage is 100% for the two parameters, and the description enriches both: it explains the practical effects of depth values (hop counts, gap recovery, paid tier for 'thorough') and confirms 'question' accepts broad/multi-part natural language. This goes well beyond the enum and field descriptions 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 this is a grounded multi-source research tool over Pipeworx's structured data sources, decomposing questions into facets and routing to 5,462 tools in parallel. It explicitly contrasts itself with ask_pipeworx and open-web search, making its purpose and unique scope unmistakable.

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

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

The description gives detailed when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, prefer ask_pipeworx for breaking/current news, and use ask_pipeworx if not signed in. It names specific alternatives and explains the depth tiers, covering both use cases and exclusions.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the return format ('top-N most relevant tools... each result is ready to call directly, no second schema lookup needed'), which tells the agent that output schemas are included and immediately usable. This is useful behavioral context beyond the annotations.

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

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

Three sentences, each serving a distinct purpose: statement of function, scope of searchable domains, and output/usage details. The list of data types is long but informative for a discovery tool. No redundant words; it is efficient without being terse.

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 the tool's purpose, when to use it, what it returns, and how results are structured ('full input schemas... ready to call directly'). With the schema and annotations covering safety and parameters, the agent has enough information to invoke it correctly. No output schema exists, but the description compensates by explaining the return format.

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

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

The input schema has 100% coverage, with all six parameters (query, q, task, search, description, limit) fully documented. The description only restates the query concept ('describing the data or task') and does not add parameter syntax or alias usage beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the semantic load.

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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a meta-search tool for discovering other tools, a function not offered by any sibling. It also details the output ('names, descriptions, and full input schemas'), making the tool's purpose unambiguous.

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

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

Explicit when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist.' It also advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' which frames it as the entry point for tool selection. No alternative tool is named, but the 'FIRST' instruction makes the intended context clear.

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

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

Although annotations already indicate read-only and idempotent behavior, the description discloses additional important traits: it fans out in parallel, soft-fails for patents (PatentsView sunset), uses a GDELT→GNews fallback, and enumerates the exact return fields (CIK, filings with URIs, fundamentals, etc.). This gives the agent critical expectations 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 longer than ideal but information-dense. It front-loads with user-phrase examples, then lists the fan-out sources and return fields in a structured, scannable way. Every sentence adds unique value, though it could be trimmed slightly without losing substance.

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 enumerates return values (CIK, company name, recent filings with URI patterns, fundamentals with specific metrics, patents, news, LEI). It also covers constraints (type must be 'company', value format, name resolution prerequisite) and failure modes (soft-fail, fallback), making it complete for the tool's complexity.

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

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

The input schema thoroughly documents both parameters (type and value) with examples and constraints, including the 'names not supported' note. The description restates this information but does not add new semantic meaning beyond what the schema already provides, so the 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 uses specific verbs like 'profile', 'brief me', and 'rundown' to clearly indicate the tool's function: generating a cross-source profile of a US public company. It explicitly distinguishes itself from siblings like resolve_entity and compare_entities by stating it returns a holistic view in one call.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also directs users to resolve_entity when only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive, repeatable operation. The description adds minimal behavioral context beyond that, mainly the 'sensitive data' framing, and does not contradict annotations. No extra details about consequences or error behavior are provided.

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

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

The description is three short sentences, each serving a purpose: statement of function, usage scenarios, and relationship to sibling tools. No wasted words.

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

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

For a one-parameter destructive tool with no output schema, the description explains what, when, and with which related tools. It does not detail return values or edge cases like deleting non-existent keys, but the idempotent annotation mitigates that gap. Overall sufficient for a simple memory operation.

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

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

Schema covers the only parameter (key) with a clear description, and the description's 'by key' adds no new semantics. Since schema_description_coverage is 100%, the baseline of 3 applies without additional parameter context.

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

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

The description clearly states the action (delete) and resource (previously stored memory) with a specific key, distinguishing it from sibling tools remember and recall. This is unambiguous and directly actionable.

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

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

Provides explicit usage conditions: stale context, task completion, and sensitive data removal. It also references remember and recall as complementary tools, but does not explicitly mention when not to use this tool. Thus slightly below 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?

The description goes beyond the annotations by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also describes the output as 'a single text blob ready to drop at site-root/llms.txt.' Annotations already cover read-only and idempotent behavior, so the description adds useful context without redundancy.

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

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

The description is three sentences long and well-structured: it starts with the core purpose, then explains the process and output, and ends with use cases. Every sentence provides valuable information without fluff or repetition.

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

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

For a tool with only 2 parameters, no output schema, and comprehensive annotations, the description covers all essential aspects: what it does, how it works, what the output looks like, and when to use it. No significant gaps remain, making it complete for its complexity level.

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

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

Schema description coverage is 100%, and both parameters ('url' and 'max_links') have clear descriptions. The tool description adds minimal extra meaning beyond the schema, such as implying that 'any URL' is acceptable and that output is a text blob, but the schema already documents each parameter adequately. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' The verb 'generate' and resource 'llms.txt file' are specific, and mentioning 'for any URL' clarifies scope. It also differentiates from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on producing the actual llms.txt file rather than checking visibility.

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 'Useful for' section lists three explicit use cases: getting a client's site indexed, drafting llms.txt for one's own project, and auditing a competitor's AI crawler view. This provides clear context for when to use the tool, though it doesn't explicitly state when not to use it or mention alternative tools, which would push it to 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?

Annotations already provide read-only, idempotent, open-world, and non-destructive hints, lowering the bar. The description adds value by specifying exactly what information is retrieved (fields, geometry type, record count, capabilities), going beyond the annotations to clarify the tool's output behavior. This is useful additional context for an agent.

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, tightly written sentence with no wasted words. It front-loads the core action ('Get an ArcGIS Feature/Map Service layer's schema') and then enumerates the return components clearly. Every word contributes to understanding the tool's 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?

With no output schema, the description effectively communicates the return value (schema fields, geometry type, record count, capabilities). It is sufficient for a simple 1-parameter tool with strong annotations. It lacks explicit usage caveats (e.g., error handling), but the provided context is adequate for typical use.

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

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

Schema description coverage is 100% with the 'url' parameter already described in detail (including an example). The description merely repeats 'by url' without adding extra semantic meaning beyond the schema's own description, so the 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 uses a specific verb ('Get'), names a clear resource ('an ArcGIS Feature/Map Service layer's schema'), and lists concrete outputs (fields, geometry type, record count, capabilities). It clearly distinguishes from siblings like 'query_layer' by focusing on schema metadata rather than data queries.

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 schema inspection but does not explicitly state when to use this tool vs alternatives or provide exclusions. The phrase 'Get an ArcGIS Feature/Map Service layer's schema' gives clear context, but no explicit 'when-not-to-use' or alternative tool references are mentioned.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by specifying the exact return fields (id, type, params, timestamps, fire_count) and the scope of 'caller's' subscriptions, which is beyond the structured metadata.

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

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

Two concise sentences: the first states purpose and return fields, the second provides usage guidance. No wasted words, and the most important information is front-loaded.

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

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

For a simple list tool with one optional parameter, the description fully covers the purpose, return fields, and usage context. The schema and annotations handle the remaining details, making it complete for an agent to invoke correctly.

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

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

Input schema fully documents the single parameter include_inactive with description. The description's mention of 'active subscriptions' indirectly clarifies the default behavior, but it doesn't add significant meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It distinguishes itself from sibling subscribe/unsubscribe tools by describing its use case as reviewing monitoring and finding IDs to cancel.

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 context for when to use it ('review what you're monitoring before adding more' or 'find an id to cancel'), implying alternatives without naming them directly. It effectively tells the agent when to call this tool versus subscribe/unsubscribe.

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

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

Annotations provide no safety hints (all false), so the description carries the burden. It discloses several behavioral traits: filing without an account returns a claim_token, the token can be reused to read resolution status, rate limit is 5 per identifier per day, and it is free with no quota usage. This goes well beyond annotations and provides actionable context.

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

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

The description is lengthier than typical but every sentence serves a purpose: usage criteria, exclusions, claim_token mechanics, rate limit, and cost. It is front-loaded with the core verb and resource, then logically organized. No fluff or redundancy.

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

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

Despite having no output schema, the description covers the key behavioral aspects: when to use (including exclusions), what to write, the claim_token flow, rate limiting, and cost. It fully prepares the agent to invoke the tool correctly and interpret the response. The nested context object is also explained in the schema itself.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful guidance beyond parameter descriptions: it explains the claim_token round-trip flow, instructs to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and clarifies how the 'type' maps to real-world scenarios. This elevates it above the baseline.

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

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

The description uses a specific verb ('Tell') and resource ('Pipeworx team') and clearly states the tool's purpose: report something broken, missing, or needing to exist. It distinguishes itself from sibling research/query tools by focusing on feedback about Pipeworx tools, not on retrieving information.

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

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

Explicitly lists when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' with instructions to file with other servers if the tool came from a different MCP server. This is model guidance with both when-to-use and when-not-to-use.

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

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

The description goes well beyond annotations by disclosing that data is self-aggregating from an analytics engine, contains no PII, consists of (pack, tool, count) tuples, and is cached for 5min-1h depending on the window. These details usefully set expectations for freshness and data shape beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is well-structured with a lead question, a returns statement, a numbered list of use cases, and a final note on aggregation and caching. Each sentence contributes distinct value without redundancy, and the most important information is front-loaded.

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

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

With no output schema, the description compensates by explicitly naming the returned components (top tools, top packs, total call volume) and the underlying tuple structure. This is sufficient for an agent to understand the tool's output, though the exact response format (e.g., JSON shape) is not specified, which is a minor gap.

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

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

The schema already provides a complete description for the single 'window' parameter with enum values and explanatory text. The description adds the nuance that caching varies by window (5min-1h), complementing the schema's existing distinction between short and long windows, so it provides extra value beyond schema 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 opens with a specific question 'What other AI agents are calling on Pipeworx right now' and explicitly states it returns top tools, top packs, and total call volume over a recent window. This distinctively separates it from sibling tools like discover_tools or search_datasets, which focus on discovery/search rather than aggregate usage trends.

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 concrete use cases are enumerated (discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs), providing clear guidance on when to use this tool. However, it does not explicitly mention alternatives or state when not to use it, so it misses the top tier of explicit 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description meaningfully adds behavioral context: it details internal filters (SEMANTIC ANCHOR with Jaccard ≥0.30, PARTITION FILTER with >20% placeholder threshold), explains the fill-check logic ('realizable_edge_pp ≤ 0... do not trade it'), and describes response contents and edge-case handling. This goes well 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?

The description is long but appropriately structured with mode breakdowns and labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries substantive information; however, the sheer density and length make it a bit heavy to parse. It earns a 4 rather than 5 because it could potentially be tightened, though the structure mitigates the length well.

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

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

Despite having no output schema, the description fully covers the response shape (opportunities[], partition_check{...}), return values, filters, edge cases, and complementary tool guidance. It addresses potential pitfalls (placeholders, thin legs, realizable vs theoretical edge) and provides enough context for an agent to decide whether to call this tool or a sibling. This is exceptionally complete for a complex tool with two 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 description coverage is 100% for both parameters, but the description adds substantial extra meaning: real-world examples for event/topic, explicit guidance on when each parameter is appropriate, and the fact that no args triggers trending_scan. It also explains the semantic anchor and partition filter behavior that relate to parameters, giving the agent a richer understanding beyond the schema's basic field 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This names the specific resource (Polymarket), the action (find arbitrage), and the method, distinguishing it from sibling tools like polymarket_fill_risk or polymarket_edges. The three operational modes (trending_scan, event, topic) are explicitly described, leaving no ambiguity about what the tool does.

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 explicitly prescribed: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. It even recommends when to use each mode ('event (recommended for a specific market)') and names an alternative tool for related needs: 'For custom sizing use polymarket_fill_risk.' This goes beyond simple context to provide clear selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description does not contradict them. The description adds substantial behavior context: model families, edge_pp_net after slippage, Kelly caps, a 24h-move warning, cache TTL, and diagnostics explaining why segments may be empty. This goes well 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 a single, very long paragraph that packs in a wealth of detail but lacks visual structure such as headers or bullets. It front-loads the core purpose, but the dense, stream-of-consciousness format makes it harder for an agent to scan key takeaways. Every sentence is relevant, but the structure could be much improved.

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 9 parameters and no output schema, the description is exceptionally complete. It defines response top-level fields, explains edge metrics and caveats (e.g., Fed bets unreliable), lists diagnostics with funnel counters, and even describes cache behavior. Callers can understand what the tool returns and why certain segments might be empty, covering all essential context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the purpose of tradeable-edge knobs (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and clarifying that min_partition_leg_kelly applies per-leg within partitions. This extra layer of parameter semantics justifies a 4.

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

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

The description opens with a specific, action-oriented purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the intended use case ('what should I bet on today') and names the three response segments, making the tool's scope clear and distinguishable from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives practical guidance on tradeable-edge knobs and explains that Fed bets surface but are excluded from ranking. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks direct exclusions.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial operational detail: the response shape (tracked, expired, snapshot_dates), trend enum values, signed edge_pp_net semantics, snapshot-gap implications, the 60-day TTL bound, and the daily-close (not intraday) computation. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the core question, then clearly organized into Args, RESPONSE, and LIMITS sections. Every sentence carries operational value, though the motivational aside about a '3-week-old wide edge' is helpful but non-essential, preventing a perfect 5.

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 present, the description fully specifies the return structure (tracked, expired, snapshot_dates), field-level semantics, trend classification, decay math, and data caveats. Given only two optional params, this is complete enough for an agent to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the days lookback/default and labels window as a 'snapshot family,' but it does not materially extend the schema's parameter descriptions; the added value is mostly contextual rather than semantic detail about the parameters themselves.

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-plus-resource structure: it 'answers how long has this edge existed and is it shrinking?' and defines itself as 'edge persistence and decay telemetry built from daily polymarket_edges snapshots.' This clearly differentiates it from sibling tools like polymarket_edges, which likely provide current edge values rather than historical persistence/decay 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?

It provides clear usage context by stating the exact question the tool answers and contrasting a fresh wide edge with a 3-week-old wide edge, making it evident when persistence/decay insight is needed. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of full explicit 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?

Despite annotations already declaring read-only/idempotent, the description adds extensive behavioral context: ladder walking, return field semantics, mode-specific risk (partial basket fills converting arb into unhedged directional positions), and the verdict types. This is far 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?

The description is quite long but well-structured with clear mode sections and a final usage directive. It is front-loaded with the core concept and each detail is relevant. Slight over-verbosity but no waste—still earns a high score for structure.

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

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

With no output schema, the description fully lists return fields for both modes, explains verdicts and risk fields, and covers edge cases like thin legs. It leaves minimal ambiguity. The only minor omission is behavior when neither market nor event is given, but the requirement is clearly stated.

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

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

Input schema has 100% coverage, but the description enriches meaning significantly: explains size_usd interpretation differs by mode (max spend vs target proceeds vs settlement notional), clarifies default side behavior, and describes the constraints. This goes well beyond the schema's descriptive text.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth, with specific single-market and basket modes. It distinguishes itself from sibling tools by explicitly targeting polymarket_arbitrage and polymarket_edges workflows.

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

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

The description explicitly says when to use this tool ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), and explains the two modes, prerequisites, and parameter roles. It provides actionable guidance for tool selection.

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

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

Beyond the annotations (read-only, idempotent), the description discloses substantial behavioral context: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type counters, and the response structure. This richly explains what the tool reports and under what conditions its output is meaningful, going far beyond the annotation hints.

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

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

The description is long but highly structured, with clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence adds functional information, but some sections, such as the detailed explanation of skipped_cross_type, could be condensed. Overall it earns its length due to the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly covers the response fields (leg-by-leg prices, top_spreads_pp), safety warnings, temporal alignment, and skip counters, including edge cases. This is exceptionally complete for a complex cross-venue analysis tool.

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

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

The input schema already provides full descriptions (100% coverage) for all three parameters. The description adds value by explaining the 'two modes' concept and how topic vs explicit params interact, but it does not introduce new parameter-level details beyond the schema's own parameter descriptions. Since the schema covers everything, a 4 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 begins with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which is a specific verb+resource statement. It also distinguishes from sibling tools by emphasizing the same-question comparison across two venues and detailing two distinct modes (topic vs explicit pairing), making the tool's niche clear.

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

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

The description clearly explains when to use the tool via two modes and provides a caution that 'most pre-mapped topics return compatibility_warning today,' implying use cases. However, it does not explicitly name alternative tools or state 'when not to use' this tool versus siblings like polymarket_arbitrage, so it falls short of 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?

Annotations already establish readOnly, openWorld, and idempotent hints. The description adds behavioral context by stating it returns attribute rows and geometry, and provides the sampling pattern. This goes beyond the schema and annotations without contradicting them, though it doesn't disclose details like pagination behavior beyond the limit parameter.

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

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

Two sentences, front-loaded with the core purpose, then parameters and return value, ending with a practical tip. Every sentence earns its place with no redundancy or filler.

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 no output schema, the description properly notes it returns attribute rows and geometry. It also indicates the URL source (search_datasets) and gives a sampling idiom. It could be slightly more complete by mentioning that geometry availability depends on out_fields, but overall it is sufficient 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 coverage is 100%, so the description doesn't need to explain every parameter. It adds value by clarifying the SQL-like nature of `where`, the comma-separated format for `out_fields`, and the sampling tip that combines `where="1=1"` with `out_fields="*"`. This enriches understanding beyond the raw schema definitions.

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

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

The description clearly states the tool queries an ArcGIS Feature Service or Map Service layer by URL, with specific parameters listed. It distinguishes itself from siblings like layer_info (which likely provides metadata) and search_datasets (which finds layers). The verb 'Query' and resource 'ArcGIS layer' make the purpose 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 tells the user the URL comes from search_datasets, which implies the intended workflow. It also gives a concrete usage example (where="1=1" + out_fields="*") for sampling. However, it does not explicitly state when not to use this tool or name alternatives like search_within, so it falls slightly short of 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond these, such as scope to the user's identifier and the fact that omitting the key lists all saved keys. It does not contradict the annotations, though it doesn't detail edge cases like missing keys.

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

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

The description is concise and well-structured, with the primary action stated first, followed by a use-case illustration, scoping context, and pairing with related tools. Every sentence adds value, and there is no wasted content.

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

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

For a simple retrieval tool with only one optional parameter, the description covers all essential aspects: what it does, when to use it, scoping, and interaction with sibling tools. The annotations confirm safety and idempotency, and no output schema is needed for such a straightforward return value.

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

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

The input schema already documents the single 'key' parameter with a clear description and examples, achieving 100% coverage. The description adds illustrative examples of keys (ticker, address, notes) but does not provide additional semantic detail beyond what the schema already conveys, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also covers the secondary function of listing all saved keys when the key argument is omitted. It clearly distinguishes this tool from siblings like 'remember' and 'forget'.

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

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

The description explicitly says when to use this tool ('look up context the agent stored earlier') and provides examples of appropriate use cases. It also names the complementary tools ('Pair with remember to save, forget to delete'), giving clear usage guidance and alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it explains the data source (evaluator-written, persisted feed), return fields (source, citation_uri, raw payload), the optional state-changing behavior of mark_read, and that polling is safe. It also mentions the same feed is available via an HTTP GET for non-agent use. This is rich, non-redundant detail.

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

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

The description is three sentences, front-loaded with the primary action. The first sentence states the purpose, the second details return fields and filtering, and the third addresses polling and alternative access. Every sentence adds informative value without 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?

For a read-only list tool with 5 optional parameters and no output schema, the description covers the essential context: data source, return structure, filtering, state-change behavior, and polling semantics. Combined with the complete schema and annotations, the tool definition is fully self-sufficient for an agent to invoke it correctly.

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

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

The input schema already provides descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description adds extra meaning by giving an example type ("sec_8k"), clarifying that 'since' is an ISO timestamp, and explaining the effect of mark_read on subsequent calls. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's function: "Pull fired events from your subscription feed." This is a specific verb+resource and distinguishes it from sibling tools like recent_changes, though it does not explicitly name an alternative. It also describes the return contents and filtering options, making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool: "Polls work fine" and "Set mark_read:true to flag returned events read so the next call only shows newer ones." It also offers an alternative for scripts/dashboards via the HTTP endpoint, but does not explicitly exclude usage or mention sibling tools, so it lacks explicit when-not guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes further by disclosing the multi-source fan-out, rate-limit fallback logic, the PatentsView API sunset soft-fail, and the parallel call nature. This fully informs the agent of the tool's runtime behavior and edge cases.

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

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

The description is lengthy but information-dense; every clause contributes meaning. It is front-loaded with the core purpose and natural-language triggers. The structure could be improved with bullet points, but the current flow is logical and free of 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?

Even without an output schema, the description specifies the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers sources, fallbacks, parameter formats, and an explicit alternative tool. For a complex aggregation tool, this is complete and self-sufficient.

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

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

Schema covers all three parameters, so baseline is 3. The description adds practical value by giving concrete examples for 'since' (ISO date and relative shorthands), explaining the 'value' parameter accepts ticker or CIK, and recommending typical monitoring windows. This goes beyond the schema's dry definitions.

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

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

The description clearly states the tool's function: a change feed for a company over a recent window, queryable via natural language examples. It lists specific sources (SEC EDGAR, GDELT/GNews, USPTO) and output structure, and differentiates from sibling entity_profile by contrasting dynamic changes vs. static profile.

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

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

Explicitly advises when to use this tool vs. entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' Also explains fallback behavior (GDELT→GNews on errors, USPTO soft-fail) and provides typical parameter usage ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds useful behavioral context: 'Stored as a key-value pair scoped by your identifier' and retention details (persistent for authenticated users, 24 hours for anonymous). This goes beyond the annotations without contradicting them.

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

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

Three sentences, each earning its place: purpose, usage guidance, and behavioral details. Front-loaded with the verb 'Save' and immediately explains the value. No redundant repetition of schema or annotations.

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 only two parameters and no output schema, the description is quite complete: it covers what to save, when to save, and with what persistence. It lacks explicit statements about overwriting or return values, but these are minor for a store operation.

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

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

The input schema already describes key and value with 100% coverage, so the description adds only marginal value. It provides illustrative examples (ticker, address, preference) and ties to the key-value model, but doesn't clarify formats or edge cases beyond the schema.

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

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

The description uses the specific verb 'Save' and identifies the resource as 'data the agent will need to reuse later,' with clear examples (resolved ticker, target address, user preference). It also distinguishes from sibling tools like recall (retrieve) and forget (delete) by explicitly pairing with them.

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

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

The description explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also gives alternatives: 'Pair with recall to retrieve later, forget to delete.' Clear context for choosing this tool over siblings.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral context: it cascades through multiple lookup endpoints, auto-disambiguates input, and returns citation URIs. This informs the agent about internal complexity and output richness without contradicting 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 well-structured: it opens with example queries, states the core purpose, gives a clear directive, and then details supported types with specific output information. Every sentence contributes value, and the formatting (e.g., 'SUPPORTED TYPES') makes it easy to scan. It is appropriately sized for the tool's complexity.

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

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

The tool has no output schema, but the description fully explains return values for both company and drug types, including IDs and citation URIs. It also covers accepted input formats and notes the internal cascading behavior. Given the tool's simplicity and good annotations, the description is complete enough for an agent to select and invoke it correctly.

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

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

Although the schema covers 100% of parameters, the description adds significant meaning by providing concrete examples for the 'value' parameter (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying that company accepts ticker, CIK, or name. It also explains the 'type' enum with details on what each type returns, exceeding the schema's descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides specific verbs ('resolve', 'look up') and resource types ('company', 'drug'), and the examples distinguish it from siblings by emphasizing it should be used 'FIRST' when an ID is needed. This is a specific, non-tautological definition.

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

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

The description explicitly tells the agent when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, implying it is the primary entry point for entity resolution. While it doesn't name alternative tools, the directive is clear and practical.

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 behavior. The description adds valuable context by describing the ranking/ordering, the return structure (ranked list with score, confidence, signal density), and the relationship to the sibling tool. This goes beyond the annotations, though it does not discuss rate limits or edge cases.

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

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

The description is two sentences, front-loaded with the main purpose and then expanding with the method and use case. Every sentence contributes useful information without redundancy or filler.

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 compensates by explicitly specifying the return format (ranked list with score, confidence, signal density per entity). It also mentions the optional models and API key context, and the use case makes the tool's scope clear. It lacks some edge-case details but is sufficient 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?

The schema already covers all parameters with detailed descriptions (100% coverage), so the description does not need to repeat them. It does add a small semantic detail about the first entity being the 'subject' for narrative, but this is also present in the schema. The description adds minimal extra parameter meaning beyond the schema, hence the baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Compare AI visibility across multiple entities side-by-side') and clearly distinguishes from the sibling tool ai_visibility_check by emphasizing the multi-entity comparison and ranking. It states exactly what is surfaced (score, confidence, signal density per entity).

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 a concrete use case ('competitive AI-marketing audits') with an example query ('does Claude know about us as well as our competitors?'), making the intended context clear. It mentions the underlying probe tool (ai_visibility_check) but does not explicitly state when to use an alternative (e.g., single-entity check), so slightly short of 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?

Adds rich behavioral context beyond existing annotations: describes the fan-out architecture, graceful partial-failure behavior, the 5-30s latency for first bundlephobia measurement, and the 'sources_failed' field. Also clarifies the NPM-only scope in v1. Consistent with the read-only, idempotent, non-destructive annotations.

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

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

The description is front-loaded with the core purpose, then systematically covers usage, output, ecosystem scope, and failure modes. Each sentence delivers essential information; no filler or redundancy. Slightly long but justified by the tool's complexity.

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

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

In the absence of an output schema, the description enumerates the return fields and structures (summary block, advisory details, links, alternative versions). It also covers performance, error handling, and ecosystem limits, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema covers both parameters with clear descriptions. The description doesn't add parameter-specific semantics but does indirectly confirm the 'version' defaults to latest when omitted. With 100% schema coverage, the 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 a specific composite check for npm packages, naming the data sources and exact information gathered. It distinguishes itself from siblings by explicitly limiting to the NPM ecosystem and noting alternatives for other package managers.

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 'use whenever' triggers with concrete examples ('is X safe / popular / small', 'what does adding lodash cost me'). It also gives exclusions, stating that non-NPM ecosystems should go to 'deps.dev:version directly', which directs to an alternative.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is known. The description adds valuable context by specifying the exact return fields: name, summary, record_count, owner/org, and Feature Service url. No contradictions with annotations.

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

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

Two sentences with no filler. Front-loaded with the core action and resource, followed by return payload and downstream guidance. Every clause 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?

Despite no output schema, the description specifies exactly what fields are returned and how to proceed with the returned url. This is complete for a discovery tool, and the schema covers parameter 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?

Schema description coverage is 100%, so the schema already documents all three parameters well. The description does not add parameter-specific detail beyond the schema but ties the url output to downstream tools, which is useful context. 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 uses a specific verb and resource: 'Search City of Falls Church GIS open geospatial datasets by keyword.' It also lists example dataset categories (parcels, zoning, public works & city services), which differentiates it clearly from sibling tools like query_layer and layer_info.

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

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

The description clearly positions this tool as the discovery step, stating to pass the returned Feature Service url to query_layer or layer_info. It gives a clear use context and mentions downstream alternatives, though it doesn't explicitly state when not to use it.

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

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

The description adds rich behavioral context beyond annotations: character offsets for verbatim verification, similarity scores, BGE-base-en embeddings, 500-char overlapping windows, and a 200K character cap with truncation flagging. No contradiction with the readOnly/idempotent hints.

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

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

The description is three well-structured and front-loaded sentences. It immediately states the core function, then provides usage guidance and technical details without redundancy. Every sentence earns its place.

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

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

Despite lacking an output schema, the description compensates by explaining return format (offsets, similarity scores), operational constraints (200K cap, truncation), and workflow pairing with ask_pipeworx_grounded. This gives an agent sufficient context to select and invoke the tool correctly.

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

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

Schema description coverage is 100% and the descriptions are already informative. The tool description adds workflow context (e.g., 'pass the text you already pulled') but does not significantly extend parameter meaning beyond what the schema provides, aligning with the baseline of 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, taking text and a natural-language query and returning top-N passages with character offsets and similarity scores. It distinguishes itself from siblings by emphasizing 'INSIDE a fetched record' and explicitly pairing with ask_pipeworx_grounded.

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

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

Provides clear context: 'Use when the record is too big to cram into the prompt' and explains that it saves context. It references ask_pipeworx_grounded as a companion but does not explicitly list alternatives or when not to use this tool, so it stops short of full 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?

Beyond annotations, the description adds significant behavioral details: OAuth account requirement, phone verification step, 10/day SMS cap, webhook auto-disabling after 10 consecutive failures, and the one-time return of the webhook signing secret. These are not present in annotations and materially inform the agent about side effects and operational constraints.

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

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

The description is a single dense paragraph but front-loaded with the core purpose and packed with useful details. Every sentence earns its place; however, a bulleted breakdown of types and channels would improve scannability without losing information.

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

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

Given no output schema, the description explains key return values (subscription id, webhook secret). It also covers prerequisites, delivery options, and limitations (cap, auto-disable). For a complex tool with nested objects and multiple subscription types, this description is highly complete and self-sufficient.

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

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

The input schema already provides 100% coverage with per-type examples and delivery field constraints. The description repeats a subset of these examples (e.g., items:["5.02"]) but does not add new parameter-level meaning beyond the schema. It acts as a helpful summary but not a semantic extension.

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 opens with a specific verb 'Create' and resource 'proactive monitoring subscription to a live-data event stream', clearly stating what the tool does and that it returns a subscription id. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on the creation act.

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 (for proactive monitoring), lists prerequisites (Pipeworx OAuth account), and even points to the alternative pull mechanism 'feed (always on — pull via recent_alerts...)' thus contrasting with a sibling. It does not explicitly state when *not* to use it, but the context is clear and enough for typical use.

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

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

Annotations already cover readOnly, openWorld, and idempotent hints. The description adds valuable behavioral context by specifying the return format (category-bucketed example questions with exact tool + argument shapes), the live catalog source, and the difference between calling with no arguments vs. a topic. No contradictions with annotations.

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

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

The description is front-loaded with user intent phrases, then flows into output, parameter, and usage details. It is a bit verbose, but every sentence contributes meaningful context, and the 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?

In the absence of an output schema, the description sufficiently explains the return value (category-bucketed examples), covers the single parameter, and provides use-case guidance. It also references related meta-tools, making it complete for an onboarding tool with one optional parameter.

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

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

The schema fully documents the single 'topic' parameter with allowed values, so baseline is 3. The description enriches this with illustrative examples ('finance', 'pharma', 'betting') and clarifies the behavior of omitting the parameter (returns a cross-category spread), adding value beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

It explicitly states when to use the tool ('when you do not yet know what Pipeworx can do for you') and names related meta-tools (ask_pipeworx, entity_profile, compare_entities) for learning purposes. While it doesn't list exclusions, the 'FIRST' directive provides clear timing 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?

Beyond annotations, the description discloses that ownership is enforced, the row is deactivated (not deleted), and historical events remain available. This goes beyond the readOnlyHint and destructiveHint annotations, adding valuable behavioral context.

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

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

The description is two short sentences, front-loaded with the action, and every sentence contributes meaningful detail without fluff.

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

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

For a simple one-parameter tool, the description adequately covers operation, side effects, and post-conditions. The output schema is absent, but the description explains what happens to the subscription and historical data, making it complete.

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

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

The schema covers the single parameter id fully with a clear description. The tool description adds no new parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool cancels a subscription by id, which is a specific verb+resource. It also clarifies ownership enforcement and deactivation, distinguishing it from subscribe and list_subscriptions.

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

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

The description provides clear context for when to use this tool (canceling a subscription) and explains ownership constraints. It doesn't explicitly mention alternatives, but the sibling list makes the distinction obvious.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds substantial behavioral context: the SEC EDGAR/XBRL fast path vs grounded pipeline routing, percent-delta math, verdict categories, citation behavior, and the fact that it replaces multiple calls. This goes well 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 moderately long but packed with useful information. It is front-loaded with trigger phrases and routes, then output details. It could be slightly trimmed (e.g., the long list of example phrases), but overall it is well-structured and every sentence contributes value.

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

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

Given the tool's complexity (two processing paths, tolerance logic, verdicts) and no output schema, the description fully explains the return structure: verdict types, actual value with citation, and reasoning. It also covers the routing behavior and use cases, making it complete for an agent to invoke correctly.

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

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

The input schema describes both parameters (claim and tolerance_pct) with full descriptions, giving 100% coverage. The tool description itself does not add much parameter-specific detail beyond the schema; the schema already provides examples and semantics. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('validate'/'verify') and resource ('natural-language factual claim'), and clearly distinguishes this tool from siblings by focusing on claim verification with verdicts. It also provides concrete trigger phrase examples that make its purpose unmistakable.

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 whenever the agent needs to check whether something a user said is factually correct' and covers both company-financial and other claims. However, it does not name alternative tools to use instead, nor explicitly state when not to use this tool, which costs a point.

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