Arcgis Phoenix

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 useful context beyond annotations: the default free model, the BYO-key cost implication for Anthropic, and the per-model return structure. This goes beyond what annotations provide, though it doesn't cover failure modes or interpretation of 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?

Three focused sentences with no filler. The main action is front-loaded, followed by key configuration details and return format. 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?

The tool has moderate complexity (4 params, no output schema). The description covers the core behavior, default model, cost caveat, and return structure, which is generally sufficient. It does not explain how to interpret score/confidence/signals or potential errors, but given the rich annotations and clear return description, it is mostly 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%, giving a baseline of 3. The description adds meaningful parameter context: it identifies the exact default model (Workers AI Llama-3.3-70b) and clarifies that passing _apiKey incurs direct costs through Anthropic, which the schema does not mention. This enriches understanding beyond the schema.

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

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

The description clearly states a specific verb and resource: probe LLMs about an entity and score visibility 0-100. It is distinct from many siblings, but does not explicitly differentiate from similar tools like scan_competitor_ai_presence, so it does not fully earn a 5.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not mention when not to use it or point to alternative tools, so it misses the 'when-not/alternatives' component 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?

The description adds substantial behavioral context beyond the annotations: it mentions routing to 5,501 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and notes it works on every tier. Annotations already declare read-only, open-world, idempotent, and non-destructive, so the added value is meaningful. However, it does not mention rate limits, error behavior, or what happens when the question cannot be routed, leaving some gaps.

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 every section earns its place: it front-loads the preference over web search, gives trigger phrases, examples, and clear escalation paths. It is structured as a compelling default entry point. A minor redundancy ('START HERE' and 'works on every tier, one fast call') is acceptable. It is not overly verbose for the amount of guidance provided.

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

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

For a tool with no output schema and a very broad scope, the description is remarkably complete. It covers what the tool does, when to use it, what it returns (structured answer with citation URIs), and how it relates to sibling tools. It also gives practical examples. This tool is well-specified for an open-ended question-answering 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 schema has 100% description coverage: the 'question' parameter is fully described and the five aliases are all documented as aliases for it. The description does not add parameter-level details beyond the schema, so the baseline of 3 is appropriate. It does give examples of questions, but these are already present in the schema's examples.

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 answers natural-language questions about a wide range of real-world data (SEC filings, FDA, FRED, patents, etc.) and routes to source tools. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research by explaining scope and use case. The verb 'answers' and resource 'Pipeworx' are 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 provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases, gives concrete examples, and states 'START HERE for most questions'. It also explains when to step up: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is excellent guidance with both positive and negative use cases.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that candidate routing improvements are enabled live and can change behavior between calls, and that results are compared against stable routing for evaluation. It also discloses the current state (no candidate active, so it matches ask_pipeworx exactly) and reassures that it is a full working router with no fallback. This adds significant behavioral context beyond annotations.

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

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

The description is four sentences that are information-dense, front-loading the beta status and identity before explaining experimental behavior. It includes specific details (5,501 tools, date, comparison process) without unnecessary fluff. Slightly longer than minimal but every sentence contributes.

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

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

For a complex tool with no output schema, the description provides essential context by referencing the identical response shape to ask_pipeworx and describing the experimental nature. It covers current behavior, usage, and evaluation, making it sufficiently complete for an agent to operate the tool correctly, though it relies on knowledge of ask_pipeworx.

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 each of the six parameters described as aliases for 'question.' The description does not add parameter-specific details, but given full schema coverage, the baseline of 3 is appropriate; no additional meaning is needed.

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 with an identical universal router (same 5,501 tools, arguments, response shape) and experimental routing improvements. It distinguishes the tool from its stable sibling ask_pipeworx by emphasizing it is the experimental edge, making 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 explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes it currently matches ask_pipeworx exactly. It contrasts with the stable router via 'results are compared against the stable router to decide what merges,' providing clear alternative context. It does not explicitly forbid use, but implies stable router exists for non-experimental needs.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals detailed behavioral traits: it extracts strictly from tool results, returns a specific structure {answer, evidence, confidence, source, fetched_at, refusal_reason}, and provides explicit refusal reasons like 'not_in_source' and 'data_truncated'. This is far richer than the annotations alone.

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

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

The description is dense but well-organized: purpose first, then process, return behavior, usage guidance, and cost tradeoff. Every sentence adds decision-relevant information, with no filler or repetition of schema 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?

Despite having no output schema, the description fully documents success and failure return shapes and refusal reasons. It covers when to use, the extra cost relative to ask_pipeworx, and the safety behavior, making it self-contained for correct 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?

The input schema covers 100% of parameters, including the question field and all five aliases, each with descriptions. The tool description adds no parameter-specific detail, so the schema does the heavy lifting; 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 this is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific process: route through 5,501 tools, fetch data, then extract answers only from tool results. It also explicitly distinguishes from ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

It explicitly says to use this tool when an answer will be 'quoted, cited, or acted on' and lists concrete high-stakes examples (financial verdicts, legal claims, medical lookups). It also names the alternative, ask_pipeworx, and advises preferring it for casual lookups due to the extra LLM call.

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/non-destructive, and the description adds substantial behavioral context: resolver confidence contract, low-confidence short-circuit, closed-market blocking, illiquidity warnings, news fallback details, and cancellation-rule parsing. It describes failure modes and safety behavior that go far beyond annotations, with no contradictions.

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

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

The description is front-loaded with the core purpose and structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It is long, but every section provides operational detail needed for correct use, so the size is justified for the tool's complexity. The use of uppercase headers improves scannability.

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

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

With no output schema, the description thoroughly explains response shapes (result.market, analysis, evidence), parent_event extraction, news fallback behavior, status codes, and resolution-rule risks. It covers edge cases such as low-confidence matches, closed/inactive markets, wide spreads, and cancellation rules, making the tool safely usable.

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 covers all three parameters with detailed descriptions, so the baseline is 3. The tool description reinforces the market parameter's accepted formats and gives fan-out examples, but it does not add substantial parameter-level semantics beyond the schema; depth and include_raw are already adequately described 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 opens with a specific verb ('Research') and resource ('a Polymarket bet'), states accepted input forms (slug, URL, question text), and summarizes the full pipeline (resolve, classify, fan out, return evidence packet + market-vs-model comparison). This clearly distinguishes bet_research from sibling tools like polymarket_edges or arbitrage tools by emphasizing single-query research across data sources.

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 provides usage guidance with 'Use for "should I bet on X", ...' and gives concrete fan-out examples across bet categories. It does not name alternative tools or list when-not-to-use scenarios, but the query patterns and extensive examples give clear contextual 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 read-only, idempotent, and non-destructive. The description adds substantive behavioral context: what data is fetched per type (10-K metrics, FAERS counts), how fiscal year offsets are handled, sorting by primary metric, and the return format with citation URIs. This goes well beyond the structured annotation fields.

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 appropriately sized given the tool's complexity, with all sentences contributing to operational clarity. It front-loads the trigger patterns and the core preference rule. The list of example phrases ('which is bigger / better / larger...') is slightly repetitive but helps NLU matching.

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 only two parameters and a clear output concept (paired data + URIs), and the description covers the input format, data source nuance, sorting behavior, and return expectations. No output schema exists, so this description fully compensates, making the tool self-contained 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?

All parameters are fully described in the schema, so baseline is 3. The description enriches the meaning of both parameters by detailing what each type value returns ('type="company" pulls LATEST 10-K...', 'type="drug" pulls FAERS...') and what the values array should contain (tickers/CIKs vs. drug names). This added context gives the agent a deeper understanding beyond the schema's property 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 opens with concrete natural-language examples ('Compare X and Y', 'X vs Y', 'rank these companies'), then states the core function: side-by-side comparison of 2–5 entities in one parallel call. It clearly distinguishes itself from sibling single-entity tools by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' The specific verb is 'compare' with a defined resource scope.

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

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

The description explicitly directs when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing direct guidance versus alternatives. It also enumerates the exact query patterns that trigger this tool, making the decision boundary clear. It doesn't state exclusions for non-comparison scenarios, but that is implied.

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 extensive behavioral context beyond the readOnly/openWorld/idempotent annotations: account/paid-plan requirements, 15-90s latency, gaps[] for unanswered facets, 'never invented', contradiction[] scanning, hop field, and citation fetchability. It even explains semantic excerpting to avoid missing answers deep in records.

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

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

The description is dense and front-loaded with the critical account constraint, and every sentence earns its place. However, it is a single long paragraph with many embedded clauses, which makes it less scannable than ideally formatted; structuring with bullets or clearer sentences would improve readability without losing content.

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

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

Given the tool's complexity and the modest annotations/schema, the description covers all necessary context: account tiers, alternatives, output format (findings packet, gaps, contradictions), latency, limitations on current-news topics, and even the resolvability of citations. No output schema exists, so this description carries full weight and does so completely.

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 schema coverage is 100%, the description significantly elaborates on the depth parameter: each level (quick/standard/thorough) is explained with facet counts and hop behavior, and the question parameter is clarified with 'Broad/multi-part is fine — decomposition is the point'. This adds meaning well beyond the schema's short 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources... in ONE call'. It clearly distinguishes from siblings by explicitly naming ask_pipeworx and noting 'this is NOT open-web search'.

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

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

Provides explicit when-to-use vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes account requirements (signed-in vs ask_pipeworx) with a signup URL. Also specifies best use cases like 'broad/multi-part questions'.

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, which covers the safety profile. The description adds valuable behavioral context beyond that: it returns top-N relevant tools with full schemas and 'no second schema lookup needed,' and it frames the tool as an initial exploration step. It doesn't mention potential edge cases (e.g., empty results), but the description meaningfully supplements 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 average but every sentence earns its place: the first sentence defines the purpose, the second lists use cases and domains, the third explains the return format, and the fourth gives strategic guidance. It's front-loaded and well-structured, though the domain list could be trimmed without losing core meaning.

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 explains what the tool returns (top-N tools with names, descriptions, and full input schemas) and when to use it. For a meta-tool of moderate complexity, this is complete enough for an agent to invoke it correctly and interpret the result. The sibling context (many tool names) reinforces why this discovery tool is valuable.

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%: every parameter (query, q, task, limit, search, description) has a clear description, including aliases. The description itself doesn't add much parameter-level detail beyond what the schema already provides, though it does offer example queries in the schema and a domain list in the text. Since the schema carries the heavy lifting, a 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 starts with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this from sibling tools by focusing on tool discovery rather than data retrieval, and it enumerates the domains covered (SEC filings, FDA drugs, etc.), making the purpose explicit and differentiating it from data-specific tools.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This tells the agent exactly when to choose this tool over the many siblings, and implies that if you already know the tool, you should call it directly.

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 this as safe, read-only, idempotent, and non-destructive. The description adds valuable behavioral context: parallel fan-out across multiple sources, specific return fields, the patent API sunset soft-fail, and the GDELT→GNews fallback chain. No contradictions found.

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 information-dense, with examples, usage guidance, output structure, and caveats all included. It is front-loaded with user-like query phrases. Slight verbosity keeps it from a 5, but every sentence contributes.

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 to rely on, the description thoroughly enumerates return categories (CIK/name, filings with URIs, fundamentals, patents, news, LEI) and their caveats. It covers input limits, source selection, fallback behavior, and relationship to sibling tools, making it fully 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?

The input schema already documents both parameters completely, including the ticker/CIK format and the 'names not supported' constraint with resolve_entity guidance. The description adds example values but no new semantic detail, matching the schema-coverage baseline of 3.

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

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

Description opens with concrete example queries and states 'full cross-source profile of a US public company in ONE parallel call', clearly identifying the tool's verb, resource, and scope. It also distinguishes from single-source lookups by naming SEC/XBRL/news and explicitly saying to prefer this over chaining 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?

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and tells the agent to use resolve_entity when only a name is available. This provides clear when-to-use and when-not-to-use guidance with a named 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 mark destructiveHint and idempotentHint; description reinforces destructive nature and adds context about clearing sensitive data. No contradiction, and the description adds modest behavioral context beyond annotations.

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

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

Two concise sentences, front-loaded with the verb and resource. Every word earns its place, with 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?

For a simple deletion tool with one required parameter and clear annotations, the description covers purpose, usage scenarios, and tool relationships. No critical information is missing.

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 already documents 'key' with 100% coverage ('Memory key to delete'). Description only reuses 'by key', providing no additional semantics, 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?

Description clearly states the action (delete) and resource (previously stored memory by key), and distinguishes from siblings by explicitly referencing remember and recall as counterparts.

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 scenarios (stale context, task complete, clearing sensitive data) and suggests pairing with remember/recall, giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown as a single text blob. It does not disclose edge-case behaviors like failure handling, but given the strong annotation coverage, this is acceptable.

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 front-loaded with the primary action, then details the process, output format, and use cases. Every sentence contributes value without redundancy, achieving an ideal balance of brevity and informativeness.

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 two parameters, no output schema, and strong annotations, the description covers the essential aspects: purpose, mechanism, output format, and typical use cases. It lacks explicit caveats about edge cases (e.g., JS-heavy or paywalled sites), but overall it is sufficiently complete for the tool's simplicity.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema fully documents parameter semantics. The description adds no extra parameter-level detail beyond what the schema provides, making a baseline score of 3 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 identifies the tool's purpose: generating a production-ready llms.txt file for a given URL. It specifies the verb ('Generate'), the resource ('llms.txt file'), and the target ('any URL'), while distinguishing it from sibling tools by focusing on file generation rather than visibility checks or competitor analysis.

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

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

The description provides clear use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which informs when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral detail about what metadata is returned, but does not mention any potential errors, rate limits, or auth requirements. This is acceptable but not exceptional.

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

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

The description is a single well-structured sentence that front-loads the action and resource, followed by a succinct list of the returned metadata. Every word earns its place with no redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema) and rich annotations, the description fully conveys the tool's purpose and return values. It lists the key outputs (fields, geometry type, record count, capabilities), making the behavior complete 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 description coverage is 100%: the url parameter is clearly described with an example. The description does not add additional meaning to the parameter itself, only to the output, so it sits at the baseline for a fully documented schema.

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

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

The description uses a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and enumerates exactly what is returned (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer, which likely fetch features rather than metadata.

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

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

The description implies the usage: use this tool when you need schema or metadata for an ArcGIS layer. However, it does not explicitly contrast with alternatives (e.g., query_layer) or state when not to use it, so the guidance is only implied rather than explicit.

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 and non-destructive. Description adds the response shape (id, type, params, created_at, last_fired_at, fire_count) and clarifies it returns active subscriptions by default, giving context beyond annotations.

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

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

Two crisp sentences front-load the purpose and return fields, then give actionable usage guidance. 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?

For a simple list operation with one optional parameter, the description covers purpose, return fields, and usage. No output schema exists, but the field list compensates.

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?

Only parameter include_inactive is fully described in the schema, including default. Description reinforces 'active subscriptions' but adds no new parameter detail beyond schema's 100% 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?

Clearly states what it does: lists active subscriptions. Provides return fields and distinguishes from subscribe/unsubscribe by mentioning use cases for adding or cancelling.

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: to review current monitoring before adding more subscriptions or to get an id for cancellation. This gives direct context against sibling tools.

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

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

The description discloses rate limiting ('5 per identifier per day'), that it is free and does not count against quota, and that filing without an account returns a `claim_token` for later status checks. It also explains the team's daily review process and signal impact, providing rich behavioral context beyond the all-false 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, every sentence carries value: purpose, use cases, exclusions, token mechanics, rate limits, and impact. Information is front-loaded and logically ordered, with 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?

The tool has no output schema, but the description covers key return behavior (claim_token and status retrieval), usage constraints, and safety-related notes. It could be slightly more explicit about error cases or full output structure, but given the tool's simplicity, the description is adequately 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 all parameters are already described in the input schema. The description reinforces key details (e.g., claim_token usage) but does not add substantially new parameter-level semantics beyond what the schema provides, 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than questions.

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 a tool returns wrong/stale data...'), along with exclusions for tools from other MCP servers and instruction to file with the appropriate server instead. It also advises what to include ('in terms of Pipeworx tools/packs') and what not to include (end-user prompts), giving clear decision 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 cover read-only and idempotent safety. The description adds valuable non-redundant context: data source (CF analytics-engine), no PII, output shape ((pack, tool, count)), and caching behavior (5min-1h). No contradiction with annotations.

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

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

The description is front-loaded with the core answer, uses a compact bullet-list style for use cases, and every sentence adds useful information. Slightly longer than strictly necessary but none of it is 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?

For a simple tool with one optional parameter and no output schema, the description covers what the tool returns, the aggregation source, privacy, caching, and intended usage scenarios. Nothing important is left unexplained.

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 already provides the enum and a basic description for 'window'. The description complements this by explaining the practical difference between short and long windows ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), adding decision-making value.

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 clear verb+resource ('Returns the top tools, top packs, and total call volume') and uniquely identifies the tool's scope (aggregate AI agent call trends), distinguishing it from siblings like discover_tools or recent_alerts.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains window selection trade-offs. Does not name specific alternative tools, so it misses the 'when-not' component, but context is clear enough for an agent to decide.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds significant context: the trending scan scope (~200 markets), Jaccard similarity threshold (≥0.30), placeholder filter (>20% returns null), response schema, fill check behavior against CLOB depth, and the recommendation not to trade when the edge isn't realizable. No contradictions with annotations.

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

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

The description is dense and front-loaded with purpose, but runs long. It uses uppercase labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure information, and every sentence is informative. It could be split into bullets for readability, hence 4 rather than 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?

No output schema exists, so the description carries the burden of explaining returns. It lists opportunities[] fields, partition_check fields, and fill_check outputs, plus edge-case behavior (skipped_low_similarity, placeholder filtering) and a pointer to polymarket_fill_risk. This is 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?

Schema already describes event and topic with examples, but the description goes deeper: it explains the internal checks (date-axis/threshold-axis, partition sum), what happens with full URLs, the cross-event union flattening, and the no-args mode not present in the schema. This adds meaning far 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' specifying the exact resource and method. It also distinguishes three modes (trending_scan, event, topic) and references sibling tool polymarket_fill_risk, making it clear what this tool uniquely 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?

Explicitly instructs when to call with no args, when to pass event, and when to pass topic, with concrete examples. It also advises against trading when realizable_edge_pp ≤ 0 and directs users to polymarket_fill_risk for custom sizing, providing clear usage boundaries.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: response segment structure, edge metrics (edge_pp_net, kelly_fraction), diagnostics funnel counters, the 24h-move warning, caching behavior ('Cached 1h at the KV level'), and the 'rare-by-design' nature of concentrated longshots. These details are not derivable from the schema or annotations.

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

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

The description is long and dense, but this is justified for a complex tool with 9 parameters and a rich response model. It is well-structured with clear sections for model families, tradeable-edge knobs, and response top-level, and it front-loads the primary purpose. Some repetition or over-detail (e.g., the exact model family formulas) could be trimmed, but overall every section 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?

The tool has no output schema, so the description carries the full burden of explaining the response. It comprehensively describes the top-level by_segment structure, the _diagnostics block, and the key edge fields. It also covers caveats (e.g., Fed signal unreliability) and filtering rationale. Given the tool's complexity, this description is exceptionally 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?

Although the input schema already has 100% description coverage, the tool description adds meaningful cross-parameter semantics. For example, it explains how min_liquidity and max_spread_pp are 'tradeable-edge filters' that drop opportunities, and it clarifies that min_kelly does not apply to partition_overround opportunities because 'basket trades don't compose to single-leg Kelly' — requiring the separate min_partition_leg_kelly knob. This goes far beyond the schema's individual parameter 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clarifies the intended use case ('what should I bet on today') and clearly distinguishes this from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on cross-referencing Pipeworx data with market prices for discovery.

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

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

The description provides clear context for when to use this tool: 'agents discover opportunities without paging hundreds of markets.' It also includes guidance on knobs (e.g., 'Set to 2 to require tight books') and explicitly explains why certain segments are excluded (e.g., Fed bets 'excluded from ranking... unreliable'). However, it does not explicitly name alternative sibling tools or state when NOT to use this tool, which prevents 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 far beyond the read-only/idempotent annotations, disclosing the full response structure (tracked, expired, snapshot_dates), explaining how snapshots are created (cache-miss writes) and what gaps mean, and noting the 60-day TTL and daily-close basis for decay calculations. This is rich behavioral context.

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

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

The description is lengthy but well-structured with Args, RESPONSE, and LIMITS sections. The analogy about fresh vs. old edges is slightly tangential, but the rest of the text is dense with necessary operational details, making it mostly concise for its complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: tracked, expired, and snapshot_dates semantics, trend and decay calculation, and interpretation of missing snapshots. It also covers limitations like TTL and daily vs. intraday data, making it 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 fully describes both parameters with details on defaults and clamps (100% coverage). The description adds no significant semantic value beyond restating the schema, so the 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 first sentence clearly states the tool's function: edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes from the sibling polymarket_edges by focusing on the time dimension.

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

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

The description explains the exact analytical question the tool answers and gives a concrete example (fresh vs. 3-week-old edge) to illustrate when persistence matters. It does not explicitly name alternative tools or state when not to use it, but the context is clear.

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

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

Annotations already declare read-only and non-destructive, but the description adds substantial behavioral detail: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and explains basket-mode risks like forced_directional_risk and partial-fill conversion to unhedged positions. It also discloses interpretation of size_usd for both modes. No contradiction with annotations.

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

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

The description is dense and information-rich, with a clear opening statement, distinct mode explanations, and a final usage directive. While it is a long single paragraph, every sentence contributes meaningful detail, and the complexity of the tool justifies the length. Minor deduction for lack of visual structure (e.g., bullet points or mode headers) that would aid scanning.

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 full responsibility for explaining return values. It enumerates all key return fields for both modes, including edge-case alerts (thin_legs, forced_directional_risk, max_clean_notional_usd), and explains the verdict options. For a high-complexity tool with dual modes and no structured output metadata, the description is remarkably 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 has 100% coverage with detailed per-parameter descriptions, so baseline is 3. The description adds cross-mode semantics that the schema fields alone do not fully convey, such as 'size_usd (default 1000 — max spend on buys, target proceeds on sells)' and the basket-mode interpretation as settlement notional. It also explains the auto-detection logic for basket side. This exceeds schema-only documentation.

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 definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges and explaining how fill risk is the prerequisite check for acting on those tools. The two modes (single-market and basket) are unambiguously described.

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

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

Explicit usage direction is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical values and warns about partial fills converting arbs into directional risk. This is exactly the kind of when-to-use vs. alternatives guidance needed.

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

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

Annotations already indicate a safe, read-only, non-destructive tool. The description significantly adds behavioral detail: compatibility_warning cases (non-equivalent bet shapes, unrelated events), temporal_alignment implications (aligned:false makes spreads meaningless), and skipped_cross_type/subtype counters. This goes far beyond what annotations provide.

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

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

The description is long but well-structured: purpose, modes, response, safety fields, and a cautionary note. It is front-loaded with the core statement and uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS). Some sentences are dense, but every part contributes value; minor redundancy like 'pre-mapped ≠ tradeable' could be trimmed.

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 and high complexity (cross-venue pairing, multiple modes, warnings), the description thoroughly covers return values (leg-by-leg prices, spread, top_spreads_pp), temporal alignment, and skipped counters. It also warns about rarity of valid spreads, giving the agent enough to evaluate whether results are trustworthy.

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 already covers all parameters with descriptions (100% coverage). The description adds functional meaning: explains how 'topic' selects pre-mapped shortcuts, how kalshi_event_ticker and polymarket_event_slug override the mapped sides, and the auto-fetch behavior. This enriches the schema but does not fully introduce new semantics not implied by 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 opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes the tool from siblings like polymarket_arbitrage by focusing on same-outcome cross-venue pricing differences, and clearly describes the two modes and the response structure.

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 TWO MODES (topic shortcuts vs explicit ticker/slug) and gives guidance on when the tool is meaningful vs when it returns warnings. It warns that 'pre-mapped ≠ tradeable' and explains compatibility warnings. However, it does not explicitly name alternative tools or state when to prefer this over siblings, though the context is clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by mentioning return of attribute rows and geometry, and provides a sampling tip. It does not cover pagination limits or error handling, but the annotations lower the burden.

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 action and key parameters, and includes a concise usage tip. No wasted words; every phrase earns its place.

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

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

For a query tool with 6 parameters and no output schema, the description covers the primary use case, parameter summary, and return type. It lacks explicit error handling or rate limit info, but the sampling tip and provenance hint (from search_datasets) make it 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 supplements with SQL-like syntax examples and a sampling pattern ('where=1=1' + 'out_fields=*'), adding practical usage context beyond the schema's parameter 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 queries an ArcGIS Feature/Map Service layer by URL, specifies the SQL-like parameters, and notes it returns attribute rows and geometry. This distinguishes it from siblings like layer_info (metadata) and search_within (geospatial search).

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 indicates it works with URLs from search_datasets and provides a sampling pattern ('where=1=1' + 'out_fields=*'), giving clear context. However, it does not explicitly state when to avoid this tool versus alternatives like layer_info or search_within.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety traits. The description adds valuable context about scoping ('Scoped to your identifier') and the list-all behavior when key is omitted, which are not in annotations. No contradictions found.

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 core action, followed by usage context and scoping/pairing information. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers purpose, usage, scoping, and sibling relationships. It sufficiently explains the return behavior (value vs list of keys) without needing additional detail.

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 parameter description already states 'Memory key to retrieve (omit to list all keys)'. The tool description repeats this and adds a bit of context about the key being optional, but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes itself by specifying the resource (saved memory) and explicitly contrasts with sibling tools (remember/forget) while also noting it avoids re-deriving context.

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

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

The description provides clear usage context: use it to look up previously stored context without re-deriving it. It explicitly pairs with remember and forget, but does not explicitly exclude alternatives or state when not to use it beyond implying it is for saved memory. Still, the guidance is strong enough for an agent to select this tool appropriately.

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

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

The description discloses a mutation – 'Set mark_read:true to flag returned events read' – but annotations declare readOnlyHint=true. This is a direct contradiction: the tool can alter persisted state when mark_read is set. The description itself is transparent, but it conflicts with the structured annotation, so per rule it scores 1 and flags an Annotation Contradiction.

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

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

The description is four sentences, each earning its place: purpose, return contents, filters/read behavior, and alternative access. It is front-loaded with the core purpose and does not repeat trivial information. 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?

For a tool with 5 optional parameters and no output schema, the description covers the main return fields (source, citation_uri, raw payload), filtering options, mark_read semantics, and an external endpoint. It lacks a bit of detail on what 'read' status means or the default sort order, but overall it gives an agent enough 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%, so the baseline is 3. The description adds a concrete type example ('sec_8k') and explains the effect of mark_read on subsequent calls, but this mostly paraphrases the schema. It does not add significant new syntax or format details beyond what the schema already provides.

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

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

The description opens with 'Pull fired events from your subscription feed' – a specific verb and resource. It distinguishes recent_alerts from siblings like list_subscriptions (which likely lists subscriptions) and recent_changes (which tracks changes), by focusing on fired alert events with payload details. The scope is explicit: alerts the evaluator wrote to the persisted feed.

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

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

The description clearly implies when to use this tool (to poll fired alerts) and provides an alternative for scripts/dashboards: 'the same feed is also at GET registry.pipeworx.io/alerts.json'. It explains filter and mark_read usage, but does not explicitly state when NOT to use it versus a sibling like list_subscriptions, so it lacks 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?

Annotations already declare read-only, idempotent, and open-world behavior, but the description adds substantial context: sources (SEC EDGAR, GDELT→GNews fallback, USPTO), failure modes (PatentsView sunset soft-fail), and return format (changes[], total_changes, citation URIs). This goes well beyond the annotations and fully discloses behavior.

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

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

The description is dense but well-organized: starts with query examples, then summarizes the core function, lists sources and fallbacks, clarifies parameter syntax, and ends with an alternative tool. Every sentence provides necessary information with no filler or repetition.

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

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

For a tool with no output schema, the description fully covers return values, parameter formats, source behaviors, and fallback/error conditions. It also gives usage guidance and sibling comparison. The description is complete enough for an agent to select and invoke this tool confidently.

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 enriches semantics by explaining the `since` parameter's accepted formats (ISO date vs relative shorthand) with examples and recommending '30d' or '1m' for typical monitoring. This adds value beyond the schema's plain 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: a change feed for a company over a recent window, with natural-language examples. It distinguishes itself from siblings by explicitly pointing to entity_profile as an alternative for static profiles, making it 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?

Gives explicit usage context via example queries ('What's new with X') and specifies when to use entity_profile instead. It also details the fan-out and fallback behavior, so an agent knows what to expect and when this tool is appropriate.

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 convey safety traits (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context about persistence ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping by identifier, which goes beyond the annotations without contradicting them. It does not detail overwrite semantics for existing keys, but the annotation coverage lessens that burden.

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, consisting of three sentences that each serve a distinct purpose: purpose, usage guidance, and persistence/related-tool info. No filler or redundant content, making it highly efficient.

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

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

For a simple tool with two parameters and no output schema, the description covers all necessary context: purpose, when to use, persistence behavior, and relationship to sibling tools. It is sufficiently 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 description coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by providing examples of what to store (resolved ticker, target address, user preference) and clarifies the key-value pairing, reinforcing the parameters' meaning with concrete use cases.

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 ('Save data') and resource ('key-value pair scoped by your identifier'), clearly indicating the tool's function. It distinguishes itself from sibling tools by explicitly mentioning recall and forget as complementary operations, making it a clear and distinct purpose.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and gives concrete examples. It also names alternative tools for related actions ('Pair with recall to retrieve later, forget to delete'), offering clear usage context 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses substantial behavioral context: each call 'cascades through several lookup endpoints internally,' and it specifies the exact return fields for each entity type (for company: ticker, CIK, company_name, citation URI; for drug: RxCUI, ingredient, brand, citation URI). This goes well beyond the annotations' safety profile.

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

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

The description is fairly long but well-structured: it front-loads the core purpose with examples, then gives usage guidance, then breaks down supported types with return details. Every sentence carries useful information, though some redundancy with the schema exists (e.g., input formats for drug names). It earns a high score for being appropriately detailed 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?

There is no output schema, so the description must explain return values, and it does thoroughly for both entity types. It also covers the tool's internal behavior (cascading lookups), usage context ('Use FIRST'), and supported inputs. Together with the annotations, the description provides a complete picture for an agent to know when and how to use the tool.

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

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

The input schema already covers 100% of parameter descriptions, giving baseline 3. The description adds extra meaning by providing concrete input examples (AAPL, 0000320193, 'ozempic'), noting auto-disambiguation for companies, and clarifying that drug names can be brand or generic. This enriches the schema but is not dramatically more than what the schema already states, hence 4.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It gives specific examples and details the two supported entity types (company, drug) with their respective output identifiers. This distinguishes it from sibling tools like entity_profile or compare_entities by focusing on the name-to-ID resolution step.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool 'replaces 2-3 manual lookups.' However, it does not explicitly state when not to use the tool or name alternative tools, so it stops short of full when/when-not/alternative coverage.

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 reveals that the tool probes each entity with ai_visibility_check, ranks results by score, and returns per-entity score, confidence, and signal density. This goes beyond the annotations (readOnlyHint, idempotentHint) and adds meaningful behavioral context. No contradiction with annotations.

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

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

The description is only two sentences, with the primary purpose front-loaded and a helpful example in quotes. Every word contributes value, and there is no redundancy or fluff.

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

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

The description explains the return format (ranked list with score, confidence, signal density) and the target use case, while the schema covers parameter constraints like entity count (2-8) and default model. It could mention potential side effects like multiple API calls, but the overall context 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?

The schema already provides 100% descriptive coverage for all parameters, including the role of the first entity as the 'subject' and the optional nature of models and _apiKey. The description adds minimal additional parameter insight beyond noting that entities are probed, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, which is a specific verb+resource action. It distinguishes itself from sibling tools like ai_visibility_check by explicitly mentioning multi-entity comparison, ranking, and identifying most/least recognized entities.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and a concrete example question ('does Claude know about us as well as our competitors?'). However, it does not explicitly state exclusions or directly compare with alternative tools like ai_visibility_check or compare_entities.

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 mark it as read-only and non-destructive, and the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This exceeds what annotations alone provide, though it doesn't detail all possible failure 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 moderately long but every sentence serves a purpose: purpose, use cases, return fields, ecosystem limitation, and failure behavior. It is well-structured and front-loaded with the core purpose, though slightly dense and could be tightened.

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

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

For a tool with no output schema, the description thoroughly explains the return block, failure modes, and limitations. It covers what an agent needs to know about performance and scope. Minor gaps like exact link structure or per-advisory detail do not undermine completeness.

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

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

Schema coverage is 100% with descriptions for both 'package' and 'version', so the schema handles parameter semantics. The description reinforces default behavior and scoped package support but does not add new parameter-level detail beyond the schema.

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

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

The description clearly states it's a composite 'should I add this npm package to my project' check in ONE call, detailing the data sources (deps.dev and bundlephobia) and output fields. It distinguishes itself from sibling tools by focusing specifically on npm package evaluation.

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

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

The description explicitly states when to use the tool: for questions like 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives a clear exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable transparency by listing the exact return fields (name, summary, record_count, owner/org, URL) and clarifying that the URL is a pointer for further queries, which is not captured in the schema or annotations.

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

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

The description is two sentences with zero wasted words. It front-loads the core purpose, then immediately provides actionable return-value details and a downstream pointer. 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?

The description is complete for a search tool of this complexity: it explains what is searched, what is returned, and how to use the result. It covers the search scope, output structure, and integration with sibling tools, leaving no significant gaps beyond what the schema already defines.

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 provides 100% coverage with clear descriptions for all three parameters (query, limit, org_id). The description adds domain context (examples of dataset types) but does not add parameter-specific semantics beyond what the schema already offers. Per rubric, the baseline is 3 for high 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 clearly states the tool's purpose: searching City of Phoenix GIS open geospatial datasets by keyword. It specifies the resource (GIS datasets), the action (search), and highlights the key output (Feature Service URL), distinguishing it 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 provides clear usage context by indicating that the returned URL should be passed to query_layer or layer_info, establishing a workflow. However, it does not explicitly discuss when to avoid this tool or compare it to alternatives like search_within, so it falls 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: returns character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and truncates inputs over 200K chars with a flag. 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 three dense, front-loaded sentences. It opens with the core action, then gives usage context, then technical specifics. Every sentence adds value with no redundancy or fluff.

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

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

With no output schema, the description properly explains what is returned (top-N passages with offsets and similarity scores) and covers edge cases (200K char truncation flag). It also provides enough algorithm detail for an agent to predict behavior. Combined with the strong annotations, the description is complete for this tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds a little extra context (e.g., 'you already pulled', examples for query) and mentions the truncation flag, but mostly reinforces schema contents. Baseline 3 is appropriate; no significant new 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record' and elaborates with a clear workflow: pass pulled text plus a query, get back top-N passages with offsets and scores. It also distinguishes itself from siblings by emphasizing it works on already-fetched text, unlike search_datasets or other tools.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also names an alternative/complement: 'Pairs with ask_pipeworx_grounded', giving the agent a clear integration path.

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

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

Annotations only mark this as mutating, idempotent, and non-destructive. The description goes far beyond that by disclosing the OAuth requirement, the return of a subscription id, the phone verification rule, the 10/day SMS cap, the webhook auto-disable after 10 consecutive failures, and the one-time signing secret. This is rich, non-obvious 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 organized with a clear lead sentence and structured sections, but it's long and redundantly restates details already in the schema (type examples, delivery payload shapes). It earns its place for auth and operational constraints, but could be tighter by referencing the schema for parameter specifics.

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

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

Given the tool's high complexity (multiple subscription types, nested params, delivery channels, webhook security), the description covers prerequisites, return value, per-channel behavior, and constraints. Without an output schema, stating the return value (subscription id) and the one-time webhook secret is essential, and it is included.

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 detailed descriptions and examples for every parameter, including nested delivery and params objects. The top description mostly repeats or lightly augments these examples (e.g., items:["5.02"] = officer change), but adds no significant new semantics beyond what the schema already provides.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the return value (subscription id) and distinguishes itself from sibling tools 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 provides clear context: it requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels. It includes exclusions (anonymous + BYO cannot persist subscriptions) and prerequisites (phone verification for SMS). While it doesn't explicitly contrast with sibling tools, the 'create' vs 'list/unsubscribe' distinction is implied.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it returns category-bucketed example questions, each with the exact tool + argument shape, drawn from a live catalog of thousands of tools. It also describes the effect of omitting or providing the topic parameter. This is rich, non-redundant 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 well-structured and front-loaded with user intents, then explains return values, call patterns, and usage context. It is somewhat lengthy but every sentence contributes to understanding the tool. No filler, though a minor redundancy exists between the repeated user phrasings and the rest of the text.

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

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

For a simple tool with one optional parameter and no output schema, the description is exceptionally complete. It explains what the tool returns, how to call it with and without parameters, when to use it (first, onboarding), and even hints at the meta-tools (ask_pipeworx, entity_profile, compare_entities). It fully covers the contextual needs 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?

Schema coverage for the single parameter is 100%, so the baseline is 3. The description adds examples ('finance', 'pharma', 'betting') and contrasts 'full spread' vs 'focus', but these largely mirror what the schema already states. No substantially new meaning is added beyond the schema.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the 'use FIRST' tool for learning what Pipeworx can do.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains call patterns (no args for full spread, or with topic). However, it does not explicitly name alternatives or say when not to use it, so it stops 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?

The description goes beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This adds valuable behavioral nuance beyond the destructiveHint=false annotation.

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

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

Two concise sentences, front-loaded with the primary action and followed by essential constraints and side effects. No unnecessary words.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, ownership prerequisite, and post-condition (deactivation, historical events preserved). It is fully 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 schema already provides 100% coverage for the single 'id' parameter, describing it as the subscription uuid returned by subscribe. The description only restates 'by id' without adding extra semantic meaning, 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?

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, distinguishing it from sibling tools like 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 gives context about ownership enforcement ('you can only cancel your own subscriptions') and points to recent_alerts for historical events, but it does not explicitly name alternative tools or provide when-not-to-use guidance. Still, the usage context is clear.

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

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

With annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds valuable behavioral context: the two distinct execution paths, the verdict categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), the inclusion of a pipeworx:// citation, and the comparative reasoning. 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?

The description is longer than ideal but every sentence adds value. It front-loads query patterns and clearly structures the purpose, routing, return format, and value proposition. The list of natural-language phrasings is somewhat redundant but useful for pattern matching; the 'Replaces 4–6 sequential calls' is a nice contextual benefit statement.

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

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

Since there is no output schema, the description correctly explains the return values: verdict, actual value with citation, and reasoning. It covers the core scenarios (financial vs. other claims) and the fallback behavior. Missing details about error handling or source unavailability, but overall the description is complete enough for an agent to 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%, with detailed descriptions for both 'claim' and 'tolerance_pct'. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate. The mention of 'exact percent-delta math' slightly reinforces the tolerance parameter but does not add new information.

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: verifying natural-language claims against authoritative sources. It uses specific verbs like 'fact check' and 'verify', distinguishes itself from siblings by describing the two execution paths (SEC EDGAR fast path for financial claims, grounded pipeline for all others), and includes example query patterns to disambiguate.

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

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

Explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives category-specific routing guidance (financial vs. other claims) and notes it replaces multiple sequential calls. However, it does not explicitly mention when not to use it or name alternative tools.

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