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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond those: it explains the routing across thousands of tools, argument filling, stable pipeworx:// citation URIs, one-call speed, tier availability, and live-news routing. This meaningfully enriches the structured annotation signal, and there is no contradiction.

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

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

The description is long but well-structured and front-loaded: the priority directive, scope, examples, and escalation path appear early. Nearly every sentence adds distinct information; the minor repetition around web-search preference is acceptable given the routing value it communicates.

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 free-text Q&A tool with no output schema, this description is complete: it explains what happens internally, what the response looks like, when to escalate to siblings, and what kinds of questions are supported. Given the broad tool's complexity, nothing critical is missing for an agent to call 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 is 100%, so the baseline is 3. The description adds semantic guidance by defining accepted question intents ('what is', 'look up', 'find', 'get the latest') and providing concrete examples that clarify the free-text 'question' parameter. This goes beyond the schema's alias-only descriptions, though the parameter meaning is still inherently broad.

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: it routes a question to one of 5,724 tools across 1,497 verified sources and returns a structured answer with citation URIs. It also distinguishes itself from siblings and web search by naming ask_pipeworx_grounded and deep_research as escalation alternatives. An agent can tell exactly what this tool is for.

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 is explicit about when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions', 'default entry point') and when not to use it ('Step up only when needed' for grounded single answers or deep_research for broad questions). It also lists query trigger words and gives concrete examples, making the selection decision unambiguous.

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 context beyond annotations: live candidate routing improvements, current equivalence to ask_pipeworx, comparison against the stable router for merge decisions, and the explicit warning that it does not fall back to anything. No contradiction exists.

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

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

The description is four sentences and front-loaded with the core identity and version relationship. It is appropriately sized for a nuanced experimental tool, though 'identical', 'same', and 'exactly' are slightly repetitive.

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 natural-language router, the description covers experimental status, equivalence to the stable sibling, current inactive-candidate state, and fallback behavior. The response shape is referred to as identical to ask_pipeworx; while no output schema exists, an agent knows the tool is full working and invocable with a question.

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

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

Schema coverage is 100% and fully documents the single logical parameter 'question' plus its five aliases. The description only says 'same arguments' and does not add parameter-specific meaning beyond 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 description states a specific role: a beta universal router identical to ask_pipeworx, forwarding natural-language questions to one of 5,724 tools with the same arguments and response shape. It also clearly marks this as the experimental edge of the stable sibling, making the distinction between ask_pipeworx_beta and ask_pipeworx explicit.

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

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

The description gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current no-active-candidate state, confirms the tool is a fully working router rather than a fallback, and signals that results are compared with the stable router, which frames when this should be chosen.

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive, but the description adds valuable behavioral detail: it extracts only from tool results, returns verbatim evidence and confidence, and provides explicit structured refusals with specific reason codes. This far exceeds the bare annotation coverage.

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

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

The description is dense but well-structured: it opens with the core purpose, then details behavior, return shape, refusal semantics, and usage guidance. Every sentence carries essential information for correct invocation and expectation-setting, with no fluff.

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

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

Despite having no output schema, the description fully specifies both success and refusal return shapes, explains the routing mechanism, and covers when to use this tool versus the alternative. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the same natural-language question. The description adds no parameter-level meaning beyond the schema, which is exactly the baseline case where the schema does the heavy lifting.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing it from ask_pipeworx via grounded extraction and explicit refusals. The verb and resource are specific, and the differentiation from siblings is 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?

It explicitly instructs agents to use this tool when answers will be quoted, cited, or acted on, and to prefer ask_pipeworx for casual lookups. It also discloses the extra LLM call cost, giving a concrete trade-off for tool selection.

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

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

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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context: account/plan requirements, parallel routing to 5,724 tools, gaps[] never invented, resolvable citation_uri, contradictions[], semantic excerpting, and latency expectations. The openWorldHint is consistent with external structured data sources even though this is not open-web search, so there is no contradiction.

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

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

The description is long but dense and front-loaded with the account prerequisite and fallback before the method explanation. Each clause adds operational value, though some repetition around ask_pipeworx alternatives 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?

For a complex tool with no output schema, the description is exceptionally complete: it explains the return packet structure, gaps[], contradictions[], citation resolution, excerpting behavior, latency, authentication, and when to choose alternatives. An agent has enough information 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?

The schema already covers both parameters at 100% coverage with detailed enum meanings. The description adds operational nuance beyond the schema: depth:'standard' re-angles unanswered gaps, depth:'thorough' is paid and chases leads, and the question parameter is explicitly allowed to be broad/multi-part.

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 1497 structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell exactly what this tool does.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking/colloquial current-news topics. It also names the signed-out fallback and depth-tier requirements.

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?

The description goes well beyond the readOnlyHint/idempotentHint annotations. It discloses that unknown metric_type or match_subtype legs are never paired, that compatibility_codes can be non-empty even when matched_pairs > 0, that temporal_alignment null means 'could not be computed' rather than 'aligned', and that Kalshi fees are not modeled. These are behavioral traits an agent needs to interpret results safely.

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 it is densely packed with field-level safety semantics and mode guidance that the agent cannot infer elsewhere, especially with no output schema. It is front-loaded with the core purpose, then modes, then response and safety fields. Some redundancy exists, but each paragraph earns its place given the tool's complexity.

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

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

Given that there is no output schema, the description does an exceptional job of documenting return behavior: leg-by-leg prices, top_spreads_pp, compatibility fields, per-entry flags, skipped counters, temporal_alignment semantics, and the fees caveat. It also covers the open-world reality that most pre-mapped topics currently return compatibility warnings, which is essential calibration for the agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful mode semantics: topic is a pre-mapped shortcut, explicit ticker/slug parameters override the topic-mapped side, and both modes run the same token-overlap matcher. This clarifies the relationship and exclusivity behavior beyond what the schema properties alone provide, though the schema already documents the individual values.

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, resource-bound statement: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It clearly distinguishes the tool's scope from siblings like polymarket_arbitrage by focusing on matched spreads for the same question, and it names the two operating modes. This is more than a tautology and gives an agent an immediate mental model.

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 the tool: comparing equivalent Kalshi and Polymarket outcomes on the same resolving question. It also gives operational guidance on modes, warns that pre-mapped topics often return compatibility warnings, and explains that spreads are gross rather than net tradeable. It does not explicitly name alternatives among siblings, but the context is strong enough to route an agent correctly.

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?

Annotations already declare readOnly, idempotent, and non-destructive hints, and the description adds rich behavioral context beyond them: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` fields, and FIGI candidate behavior on ambiguous matches. No contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose, then organized with uppercase labels like 'SUPPORTED TYPES' and concrete examples. Some phrases are redundant (e.g., explaining figi_candidates in two ways), but most sentences add necessary operational detail.

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

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

With no output schema, the description fully covers what the tool returns: source-labelled identifiers, unresolved identifiers, figi_candidates, and the RxNorm citation. It also covers failure modes and enrichment degradation. An agent has enough information to call it correctly and interpret results without additional lookups.

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 already strong. The description goes further by explaining the `value` parameter's exact semantics: pass only the entity name, never the full noun phrase, and for bonds use the issuer as printed. It also explains how ISINs, tickers, CIKs, and drug names map to the two supported `type` values.

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: resolve a user-spoken name into canonical/official identifiers. It articulates exactly what it is for (supplying IDs other tools require) and includes concrete query patterns, making it immediately distinguishable from siblings like entity_profile.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported entity types and warns about bond-issuer input formatting. It does not explicitly name sibling tools as alternatives or state when to avoid this tool, but the 'FIRST' instruction strongly signals precedence.

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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds crucial behavioral context: defines the verdict enum, explains could_not_verify means the check did not happen and must not be treated as evidence, distinguishes unsupported, and outlines the routing logic. This significantly helps the agent interpret results correctly.

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 densely informative, with front-loaded trigger phrases and well-organized sections (purpose, paths, return values, error semantics). While verbose, every sentence serves a purpose for a complex tool, so it earns a high score though not perfect conciseness.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return values (verdict, actual value, citation, reasoning), error semantics (could_not_verify vs unsupported), and the two routing paths. It provides all necessary context for an agent to select and invoke the tool correctly.

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

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

Schema covers both parameters with 100% coverage, and the description adds extra semantics: tolerance_pct overrides implied wording, has a range (0.5-50), and is recommended for hallucination detection. Claim examples clarify expected input format. This elevates beyond the schema baseline.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with trigger phrase examples. It distinguishes from siblings by explicitly noting it replaces 4-6 sequential calls (NL parsing → entity resolution → data lookup → comparison), making its unique role 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two processing paths (company-financial vs other claims). It implies alternatives by saying it replaces 4-6 calls, but does not name specific sibling tools to avoid, so slightly below full marks.

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