Arcgis Cary

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable behavioral context beyond that: the default model, the BYO key cost implications, and the return structure ({score, confidence, signals, raw_response} + combined view). It does not contradict annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by model specifics and return format. Every sentence carries useful information and there is 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?

With no output schema, the description responsibly explains return values. It covers use cases, model options, cost behavior, and input nuances (context parameter for disambiguation). The tool is simple enough that this is complete for an agent to select and invoke it.

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 rich parameter descriptions. The description reinforces key semantics by mentioning the default model for 'models' and that '_apiKey' is only needed for Anthropic, plus the direct-cost implication. This adds modest value beyond the schema's already-explicit 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 identifies a specific action (probe), a resource (one or more LLMs), and an output (visibility score 0-100 per model). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on per-model scoring and the probe-like nature.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains important model selection/cost trade-offs (default free model vs. BYO Anthropic key). It does not explicitly name alternatives or when-not-to-use, so it lacks the full 'when/when-not' guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the description doesn't need to repeat those. It adds useful context about routing to 5,564 tools and returning stable pipeworx:// URIs, but doesn't discuss potential latency, failure modes, or citation format details beyond the URI. It doesn't contradict annotations, but adds limited extra behavioral depth.

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 densely packed with the most critical information first: the preference over web search, the scope, and the entry-point status. The examples and escalation logic are valuable, but the length might overwhelm; still, every sentence serves a purpose in guiding tool selection and usage. Slight redundancy with repeated phrases like 'START HERE' 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?

Given the tool's complexity (routing across thousands of tools) and the rich sibling context, the description is thorough in covering when and why to use it, but it lacks details on return structure, error handling, or rate limits. Since there's no output schema, the description should explain what a typical answer looks like (it mentions citation URIs but not the actual structured answer format). This is a notable gap for a tool that claims to return structured data.

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

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

The schema covers the question parameter with aliases and examples, but the description emphasizes the natural language input and provides usage examples that clarify the expected format. It explains that the question can be any factual query, which is helpful beyond the schema's basic field description. Since schema coverage is 100%, this is baseline 3, plus the examples and explicit 'question in natural language' raise it to 4.

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

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

The description clearly states the tool routes questions to a vast array of structured data sources and returns cited answers, distinguishing it from web search and sibling tools like ask_pipeworx_grounded and deep_research. It explicitly lists covered domains (SEC, FDA, FRED, etc.) and provides concrete examples, making the purpose unmistakable.

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

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

It provides explicit guidance on when to use this tool ('START HERE for most questions', 'prefer over web search') and when not to, escalating to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for multi-part questions. This effectively sets usage boundaries and alternatives, going beyond minimal context.

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

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

Annotations already cover readOnly/OpenWorld/idempotence, and the description adds valuable beta-specific behavior: live candidate routing experiments, the current no-candidate state, comparison against the stable router, and the clarification that it 'falls back to nothing' and is a fully working router. No description conflicts with the annotations.

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

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

The description is a few sentences but every part earns its place: current candidate state, comparison role, and fallback behavior. It is not terse, but it is efficient and avoids repeating schema details, with the most important identity information front-loaded.

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

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

For an experimental sibling, the description provides enough: state fields, routing scope, live candidate mechanism, relationship to stable router and the current match. Without an output schema, it refers to 'same response shape' for ask_pipeworx, which is acceptable for a known parent tool but could be slightly more explicit if an agent only looked at this definition.

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

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

Schema description coverage is 100%, with all parameters explained as aliases for `question`. The description adds the useful meta-information that the tool accepts the same arguments as ask_pipeworx, but no additional syntax or detail needed; the schema carries the semantic weight.

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 a beta universal router with candidate routing improvements, explicitly tied to the stable ask_pipeworx via 'identical universal router (same 5,564 tools, same arguments, same response shape)' and tagged as 'experimental edge.' It distinguishes itself from the sibling ask_pipeworx by being the newest/experimental variant while noting it currently behaves identically.

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 text gives explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that the last candidate was retired so it currently matches ask_pipeworx. It doesn't provide exclusions or describe when to prefer ask_pipeworx_grounded, but the when-to-use guidance is clear and meaningful.

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 (readOnly, idempotent), the description discloses refusal reasons (e.g., 'not_in_source', 'no_tool_match'), the exact return structure, and the extra LLM call cost. This adds substantial detail about tool behavior and failure modes.

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 each subsequent sentence provides unique value: routing details, return format, usage guidance, and cost trade-off. No filler; every sentence earns its place.

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

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

Despite lacking an output schema, the description fully specifies the success response and all refusal reasons. It also covers cost, alternatives, and high-stakes use cases, making the tool's behavior completely clear.

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

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

Schema coverage is 100% with each parameter described as an alias for 'question'. The description does not add new parameter semantics, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers using ONLY tool results. It distinguishes from sibling ask_pipeworx by noting identical routing but grounded extraction.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool versus the 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?

The description is exceptionally transparent about behavior beyond the annotations. It discloses parallel fan-out, resolver contract fields (market_match_confidence, market_match_score, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquidity warnings, news fallback behavior, and cancellation-rule parsing. These details go far beyond the readOnly/openWorld/idempotent annotations and provide critical context for safe agent use.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) that aid scanning. Every section adds necessary operational detail, and there is no filler. However, the sheer length may impose a token burden on an agent, so it earns a 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?

With no output schema, the description must compensate by explaining return values, and it does so comprehensively: result.market fields, result.analysis fields, result.evidence shape, resolver contract fields, parent_event extractor, news fallback attributes, and status values. It also covers edge cases like closed markets, wide spreads, and cancellation-rule risk. This is complete for a complex research tool.

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

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

The input schema already has 100% coverage with detailed descriptions for all three parameters, including examples for 'market', enum values for 'depth', and size implications for 'include_raw'. The description enriches the schema by illustrating fan-out examples and classifier categories, but it does not substantially change the meaning of the parameters themselves. 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 opens with a specific verb and resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly defines the tool's scope, inputs (slug, URL, or question text), and outputs (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like ask_pipeworx or validate_claim by its bet-focused research and fan-out behavior.

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

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

The description provides explicit usage guidance: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also gives concrete examples of when the tool is appropriate (BTC bets, Fed bets, sports championships). However, it does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral detail: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling for AAPL/NVDA, sorting by primary metric, and returning paired data with citation URIs. This goes well beyond the structured metadata and provides rich behavioral transparency.

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

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

The description is dense and front-loaded with trigger phrases, but it packs a lot of detail (data sources, fiscal-year handling, sorting, return format) into a few sentences. Each clause earns its place, though the sentence about fiscal years could be trimmed without losing core purpose. Overall, 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?

With no output schema, the description compensates by explicitly stating what is returned (paired data + citation URIs) and how results are sorted, while also covering entity-type-specific behavior. Combined with strong annotations and parameter guidance, the tool is fully understandable for selection and invocation.

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

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

Schema coverage is 100% for both parameters, but the description meaningfully enriches them: 'type' semantics are broken down by entity type (company vs drug) with specific data pulled, and 'values' format is clarified with examples (tickers/CIKs, drug names) and count constraints. 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 specifies 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with a clear verb (compare) and resource (entities). It distinguishes itself from siblings like entity_profile and research tools by explicitly positioning itself as the comparative counterpart, making its purpose unmistakable.

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

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

The description provides explicit trigger phrases ("Compare X and Y", "X vs Y", "which is bigger / better", "rank these companies") and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives clear when-to-use guidance and names the alternative pattern it replaces, exceeding basic usage context.

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

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

Adds extensive context beyond the readOnly/openWorld/idempotent annotations: never invents data (gaps[]), returns contradictions[], cites with stable pipeworx:// URIs, semantically excerpts large records, explains hop behavior, account/plan requirements, and expected latency. 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 information-dense; every sentence conveys a distinct fact (account requirements, parallel routing, gaps[], contradictions, timing, alternatives). It is front-loaded with the most critical caveat (account required) and flows logically. Slightly verbose but justifiable for the tool's complexity.

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

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

Very complete: no output schema, so the description thoroughly describes the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). Also covers prerequisites, pricing, timing, and sibling tool differentiation. No critical gaps.

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

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

Schema covers both parameters with descriptions, but the tool description enriches them further: explains the depth enum in detail (quick=3, standard=3 with gap-recovery, thorough=6 paid), and clarifies that 'question' accepts broad/multi-part queries. This is well beyond the baseline 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 uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,564 tools IN PARALLEL'. It clearly distinguishes from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx.

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

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

Explicitly provides when-to-use and when-not-to-use: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also explains depth-level selection context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context by explaining what the return payload includes (names, descriptions, full input schemas with curated examples) and that each result is directly callable without a second lookup. This is more detailed than typical annotation-covered behavior, hence a 4.

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 composed of four sentences, each serving a distinct purpose: definition, usage, behavior, and priority guidance. The domain list is long but informative; no sentence is wasted. It is slightly dense but appropriately sized for a tool descriptor, earning a 4.

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 compensates by explaining what the tool returns (top-N tools with schemas and examples) and how to use the results directly. It covers the discovery use case comprehensively, including the 'call this FIRST' context and the 'not just one answer' qualifier. This is complete for a discovery tool.

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

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

Schema description coverage is 100% – all six parameters (query and its aliases plus limit) have descriptions. The description does not add semantic value beyond the schema; it only refers to the returned tools' schemas, not the input parameters. This matches the baseline of 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 opening sentence, 'Find tools by describing the data or task,' provides a specific verb and resource, clearly establishing the tool's function. The description further distinguishes this from siblings like search_within or search_datasets by framing it as a discovery meta-tool across many domains, and the directive 'Call this FIRST' reinforces its unique role.

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: 'Use when you need to browse, search, look up, or discover what tools exist' and lists numerous domains. It also implies when not to use it ('not just one answer'), indicating that if a single specific tool is already known, this discovery layer may be unnecessary. While no alternative tool names are given, the guidance is actionable and clear.

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

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

Although annotations already declare read-only, idempotent, and non-destructive behavior, the description adds substantial behavioral context beyond those annotations. It details the fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), discloses the patents soft-fail due to USPTO API sunset, and explains the GDELT→GNews fallback for news. This gives the agent important expectations about what the tool will return and how it might degrade.

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 absolutely necessary but every sentence carries useful information. It is front-loaded with examples and a clear purpose statement, followed by a structured list of return fields. The examples are repetitive but help the model identify user intents. It earns a 4 for being appropriately sized, though it could be trimmed.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: it lists `cik`, `company_name`, `recent_filings` (with count and URI format), `fundamentals` (specific fields and sort order), `patents` (with sunset caveat), `news` (with fallback), and `LEI`. It also specifies input constraints and an alternative tool. This is a complete and self-sufficient description for a complex tool.

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

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

The input schema already has 100% coverage, describing both `type` (with enum and explanation) and `value` (ticker or zero-padded CIK, names not supported). The description repeats these constraints but does not add new parameter-level semantics beyond what the schema provides. Baseline of 3 applies because the schema is thorough.

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 example queries and then clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes itself from related tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', which differentiates it from sibling tools like single-source lookup tools.

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

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

The description provides explicit when-to-use guidance: 'when the user asks for a holistic view' and states a clear preference over chaining multiple lookups. It also gives a direct alternative: 'names not supported (use resolve_entity first if you only have a name)'. This is clear and actionable.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, setting a lower bar. The description adds useful context by specifying the resource ('previously stored memory') and the purpose ('clear sensitive data'), but doesn't detail irreversible effects or behavior on nonexistent keys, which the annotations partially cover.

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 action, followed by concise usage scenarios and a pairing note. Every sentence adds value with zero waste.

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

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

For a simple one-parameter tool with good annotations and a fully documented schema, the description covers purpose, usage, and context. The output schema is absent but not needed for a deletion tool. It is complete and well-rounded.

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 fully documents the single parameter 'key' with a description ('Memory key to delete'), and the schema coverage is 100%. The description adds no extra parameter semantics beyond confirming the key-based deletion, so 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 uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly stating what the tool does. It distinguishes itself from siblings by explicitly pairing with 'remember' and 'recall', establishing its role in the memory lifecycle.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also names related tools ('remember and recall'), giving clear context for when to choose this tool over 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 read-only and idempotent behavior, so the description adds value by disclosing the internal operations: fetches the page, extracts title/description/key links, and emits standard markdown. This provides useful context about network calls and output format beyond what annotations convey.

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

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

The description is efficiently worded, front-loaded with the main purpose, and every sentence contributes value. It covers purpose, behavior, output, and use cases in a compact paragraph.

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 2-parameter tool with strong annotations and full schema coverage, the description is complete. It explains the output format ('standard llms.txt markdown format'), use cases, and behavior, so 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?

Schema description coverage is 100%, so the baseline is 3. The description adds context like 'any URL' and 'single text blob' but doesn't provide additional parameter-level details beyond what the schema already documents.

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

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

The description clearly states the tool 'generates a production-ready llms.txt file for any URL', with a specific verb and resource. It explains the process (fetches, extracts, emits) and differentiates from sibling tools by focusing on the llms.txt output.

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 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'). It doesn't explicitly name alternatives, but the purpose is distinct enough that 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description adds the specific outputs (fields, geometry, record count, capabilities) but no additional behavioral context like auth requirements or rate limits. Given the strong annotation coverage, a 3 is appropriate.

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, compact sentence that front-loads the purpose and clearly enumerates the return values. Every word adds value, with no wasted phrasing. It is exemplary in conciseness while remaining informative.

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

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

For a simple tool with one required parameter, no output schema, and strong annotations (readOnly, idempotent), the description sufficiently covers the tool's behavior and expected outputs. It tells the agent exactly what data it will receive (fields, geometry, count, capabilities), so 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?

The schema covers the single 'url' parameter with a clear description, and the description reiterates 'by url'. Since schema description coverage is 100%, the parameter meaning is fully documented. The description adds no extra syntax or format details beyond what the schema already 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 verb 'get' and the specific resource (ArcGIS Feature/Map Service layer's schema), and enumerates the exact information returned (fields, geometry type, record count, capabilities). This distinguishes it sharply from sibling tools like query_layer and search_within, which focus on data retrieval rather than schema inspection.

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: when you need a layer's schema by URL. It implicitly distinguishes from alternatives by focusing on schema, not data. However, it does not explicitly state when not to use it or name alternative tools for data queries, which would earn 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 readOnly, idempotent, and non-destructive. The description adds context by specifying the caller scope and the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), which is useful 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 two sentences, front-loaded with the main action, and includes only essential information. No fluff or redundancy.

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

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

The tool is simple (one optional param, no output schema), and the description fully covers its purpose, return fields, and usage context. Listing the return fields compensates for the lack of an output schema.

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

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

Schema coverage for the one parameter (include_inactive) is 100%, so the schema carries the meaning. The description's mention of 'active subscriptions' aligns with the default behavior but doesn't add significant new semantics beyond the schema.

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

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

The description uses a specific verb and resource: 'List the caller's active subscriptions.' It clearly states the scope (caller's own) and distinguishes from sibling tools like subscribe/unsubscribe by tying to monitoring and cancellation.

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

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

The description explicitly says when to use it: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance and references actions (adding, canceling) that map to sibling tools, even though it doesn't name them.

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

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

Annotations are minimal (readOnlyHint=false, etc.), so the description carries the burden. It discloses concrete behaviors: unauthenticated filing returns a claim_token, passing that token later reads status/changes, rate-limited to 5 per identifier per day, free/no quota impact, and team reads digests daily. 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 every sentence contributes: purpose, usage, exclusions, token mechanics, rate limits. Some redundancy exists (e.g., 'ONLY for tools served by this Pipeworx connection' is restated in 'Pipeworx tool names are the ones this connection lists'), but it remains front-loaded with the core purpose and structured logically.

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 4 params, 0 required, no output schema, and nested objects, the description covers all necessary context: what triggers use, what to include, what to avoid, how to follow up via claim_token, and operational details (rate limit, quota). No return schema exists, but the claim_token behavior is clearly explained, making the tool's workflow fully understandable.

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% (baseline 3), but description adds value beyond it: explains the claim_token flow in context ('Filing without an account returns a claim_token') and gives content guidance for the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enhances usability beyond raw schema definitions.

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

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

The description uses specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly frames it as a feedback/reporting channel. It distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues with Pipeworx tools rather than querying or discovering 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?

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear exclusion: 'ONLY for tools served by this Pipeworx connection' with guidance to file with another server for external tools. Also includes a disambiguation step ('Not sure? Pipeworx tool names are the ones this connection lists'), making usage conditions 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). This is a strong addition, exceeding the baseline expectation.

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 information-dense. It leads with a clear purpose, follows with actionable use cases, and closes with transparency details. No wasted words; every sentence contributes 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 the absence of an output schema, the description sufficiently describes return values ('top tools, top packs, and total call volume') and the simple data structure ('pack, tool, count'). It also covers window semantics and caching, making the description complete for this simple tool.

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

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

Schema description coverage is 100%, with the parameter 'window' fully documented in the schema (enum values and meaning). The tool description repeats the window options but adds no 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 what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window'. It uses a specific verb ('Returns') and identifies the exact resource ('top tools, top packs, call volume'), making it distinct from sibling tools like discover_tools or search_datasets.

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

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

The description explicitly lists three 'Useful for' scenarios, providing clear guidance on when to use this tool. However, it does not explicitly name alternative tools or state when NOT to use it, which would have earned 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 indicate read-only, idempotent, non-destructive behavior, and the description adds rich context beyond that: fill check against live CLOB depth, realizable vs theoretical edge, 'do not trade' warning when realizable <= 0, Jaccard similarity threshold, partition filter with placeholder fractions, and response structure. 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 long and detailed, but well-structured with clear labels and sections. It is denser than necessary, but the complexity of the tool justifies much of the length. It could be slightly condensed without losing essential information.

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

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

For a tool with no output schema and two optional params, the description is exceptionally complete. It covers all modes, inputs, outputs, caveats, edge cases, fallback behavior, and related tools. The absence of an output schema is compensated by describing the response fields and conditions.

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

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

Schema coverage is 100% with both params described, but the description adds substantial meaning: the no-args default trending scan, event vs topic mode semantics, examples of each, and acceptance of full Polymarket URLs. It clarifies the behavior and expected input formats beyond the schema descriptions.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', providing a specific verb, resource, and methodology. It also distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage scanning and explicitly referencing polymarket_fill_risk for custom sizing.

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

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

The description provides explicit usage guidance: call with no args for trending_scan, use 'event' for a specific market, and use 'topic' for cross-event scanning. It includes concrete examples, explains trade-offs (cross-event catches patterns single-event misses), and distinguishes when to use polymarket_fill_risk.

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

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

The description adds substantial behavioral context beyond the annotations: caching at the KV level, exclusions like Fed bets (with rationale), the 24h-move warning, and the per-leg Kelly behavior of partition overrounds. It also details internal filters like placeholder slugs and funnel diagnostics, making behavior highly transparent without contradicting annotations.

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

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

The description is long and dense, but it is well-structured with clear sections (model families, response segments, knobs, diagnostics) and front-loaded purpose. Every sentence provides useful detail, but the sheer volume of implementation specifics (e.g., per-sport alpha values) may be more than needed for a typical agent invocation, so it is not maximally concise.

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 the lack of an output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics), the conditions that cause empty segments, and the tradeable-edge filters. It gives enough detail about the tool's behavior and response shape to invoke it correctly and interpret results, making it complete for its 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?

Input schema already covers 100% of parameters, so the baseline is 3. The description adds value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining nuanced distinctions like min_kelly vs min_partition_leg_kelly (parent vs per-leg) and why partition arbs always return kelly_fraction_half=0. This clarifies semantics beyond the schema's individual 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+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes the tool from siblings by positioning it for 'what should I bet on today' and avoiding the need to 'page hundreds of markets.' This is a clear, differentiated purpose statement.

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 context for use: it is 'Built for "what should I bet on today"' and explains how knobs like min_liquidity/max_spread_pp filter unrealizable edges and how diagnostics reveal why a segment might be empty. However, it does not explicitly name sibling tools or state when to prefer an alternative, so it lacks explicit 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 readOnlyHint/idempotentHint, which aligns with the 'tracker' name. Description adds valuable contextual behavior: history depth limited by 60-day TTL, snapshots written on cache-miss, and decay computed from daily closes of edge_pp_net. 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?

Long but every sentence earns its place: purpose, args, response structure, and limitations are clearly sectioned. Front-loaded with purpose, then organized details. No fluff or repetition.

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

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

No output schema exists, but the description thoroughly documents response fields (tracked[], expired[], snapshot_dates[]), edge cases (gaps, cache-miss), and computational details (decay from daily closes, TTL). Complete for a complex telemetry 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 baseline is 3. Description reaffirms 'lookback, default 14, max 30' and 'window snapshot family' but adds no significant meaning beyond the schema. The response section explains how parameters affect output but not the parameter syntax itself.

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 a specific verb phrase ('Edge persistence and decay telemetry') and a clear research question ('how long has this edge existed and is it shrinking?'). This immediately distinguishes it from siblings like polymarket_edges (likely current edges only) and polymarket_arbitrage.

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

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

Provides strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying when to use this tool. Does not explicitly name alternatives, but the usage context is clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not required to re-state safety. It adds substantial behavioral context: 'walks the ladder', per-leg fill detail, thin_legs[], forced_directional_risk, and warns about partial fills being the dominant loss mode. Slightly lacking explicit statement that no trade is executed, but annotations cover that.

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

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

The description is long but information-dense, with every clause contributing to the tool's understanding. It uses all-caps markers (SINGLE-MARKET, BASKET) to segment modes, and it front-loads the core purpose. It would benefit from line breaks, but the structure within a single paragraph is acceptable 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?

For a complex two-mode tool with no output schema, the description is remarkably complete. It lists the exact return fields for each mode, explains the meaning of theoretical vs realizable sums, and frames when to apply the tool. It also covers edge cases like thin legs and forced directional risk. No significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful interpretation beyond schema text: it clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode, and explains the auto-default for side. This goes beyond the schema's field-level 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+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by naming two modes (single-market and basket) and explicitly references polymarket_arbitrage and polymarket_edges as related but different tools. The purpose is unmistakable.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why partial fills convert arb to unhedged directional risk, giving a clear rationale. This is exemplary usage 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 and idempotentHint, but the description goes far beyond by detailing safety fields: compatibility_warning's two trigger cases, temporal_alignment's impact, and skipped_cross_type/subtype counters. It also discloses real-world limitations (most pre-mapped topics are not tradeable). 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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and a strong front-loaded first sentence. Every sentence contributes meaningful detail, though it could be slightly more concise without losing essential context.

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

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

Even with no output schema, the description enumerates the key response elements: leg-by-leg prices, matched spread, compatibility_warning conditions, temporal_alignment, and skipped counters. It covers edge cases like unmatched events and temporal misalignment, making it nearly self-contained for a complex tool.

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

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

The schema already provides 100% description coverage for all three parameters. The description adds valuable semantics by explaining the two modes, the exact list of topic shortcuts, and the override behavior (e.g., 'Overrides the topic-mapped Kalshi side'). This enhances understanding beyond schema, but the schema already does heavy lifting.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's scope and differentiates it from likely siblings like polymarket_arbitrage by focusing on cross-venue equivalence. The two modes and the note about non-equivalent bet shapes further clarify the tool's specific role.

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 presents TWO MODES (topic shortcuts vs. explicit tickers) and includes practical warnings like 'pre-mapped ≠ tradeable' and conditions under which compatibility_warning fires. However, it does not explicitly contrast this tool with sibling tools (e.g., polymarket_arbitrage), so it falls short of a full 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 destructiveHint=false, so the safety profile is clear. The description adds context about the return type ("attribute rows (and geometry)"), the SQL-like query semantics, and the sampling shortcut, which enriches the behavioral model beyond the annotations without contradicting them.

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

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

Two crisp sentences pack the core purpose, source relationship, available parameters, return type, and a practical sampling example. No filler words. The opening verb makes the tool's action immediately understandable, and all content 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 well-documented parameters and no output schema, the description is highly functional: it specifies the source data type, the parameter set, the return payload (attribute rows + geometry), and a helper tip. It does not detail the default limit or pagination behavior, but these are already in the schema, so the overall package is complete enough for an agent to operate.

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 every parameter has a detailed description (url, limit, where, offset, order_by, out_fields). The description repeats parameter names but does not add semantics beyond the schema, such as data type nuances or interaction effects (e.g., how offset interacts with limit). Baseline 3 is appropriate because 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 opens with a specific verb and resource: "Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets)." This clearly distinguishes it from sibling tools like search_datasets (which finds datasets) and layer_info (which presumably describes layer metadata), while also stating the exact function.

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 phrase "from search_datasets" indicates a prerequisite workflow, and the tip "Use where="1=1" + out_fields="*" to sample" provides concrete guidance. However, it does not explicitly state when not to use this tool or name alternative tools for different operations, so it falls just short of the 5-level bar.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds meaningful context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the behavior when the key is omitted (lists all saved keys). This enhances the agent's understanding of side effects and access control without contradicting annotations.

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

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

The description is well-structured and front-loaded with the core action, but the final sentence 'Pair with remember to save, forget to delete' is somewhat redundant given the sibling tools and earlier mention of remember. Overall, it is concise and every sentence has value, but there is minor repetition that prevents a perfect score.

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 optional parameter, strong annotations, clear schema), the description covers purpose, usage, scoping, and related tools. It also explains the list-all-keys behavior, which substitutes for a missing output schema. No critical gaps remain for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, and the schema already describes the `key` parameter with the 'omit to list all keys' behavior. The description echoes this detail but does not add new parameter-level meaning, 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 opens with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys' — clearly identifying the tool's resource and behavior. It also distinguishes itself from sibling tools by explicitly referencing remember and forget, making its role in the memory workflow 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?

Provides explicit guidance on when to use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names companion tools (remember to save, forget to delete), giving clear alternatives and context within the sibling set.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description explicitly states that setting mark_read:true flags returned events as read and affects subsequent calls, which is a persistent state change. This directly contradicts the read-only hint, requiring a score of 1 per the rubric.

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

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

The description is four sentences, front-loaded with the primary purpose, and each sentence provides necessary information (return fields, filtering, mark_read behavior, alternative endpoint). No fluff or redundancy.

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

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

Despite having no output schema, the description explains the return payload structure, filter options, mark_read semantics, polling suitability, and an alternative access method. This provides a complete picture for the agent to invoke the tool correctly.

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

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

Schema coverage is 100% and descriptions are clear, but the description adds meaningful context beyond the schema: it gives an example filter type ('sec_8k'), clarifies the 'since' parameter uses an ISO timestamp, and explains the consequence of mark_read on future calls. This adds value beyond the structured fields.

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 ('Pull') and resource ('fired events from your subscription feed'), and details the return fields (source, citation_uri, raw payload). This clearly distinguishes it from siblings such as recent_changes or list_subscriptions.

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

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

The description provides clear usage context: it is suitable for polling, and it offers an external alternative (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It does not explicitly name sibling tools as alternatives, but the guidance is adequate.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), the PatentsView API sunset and its soft-fail behavior, and the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). This is rich behavioral context not available from annotations alone.

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

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

The description is a single dense paragraph but front-loaded with example queries that quickly convey intent. Every sentence contributes substantive details (sources, fallback, parameters, return shape, alternative tool). It is slightly verbose but not padded; the length is justified by the tool's multi-source 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?

For a tool with no output schema, the description fully covers what to expect: sources, fallback logic, return fields (changes[], total_changes, citation URIs), rare edge behaviors (PatentsView soft-fail), and a clear comparison to entity_profile. This is sufficient for an agent to select and invoke the tool correctly in diverse scenarios.

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

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

The input schema already provides 100% coverage for all three parameters, including the enum for type, date formats for since, and ticker/CIK examples for value. The description adds example query phrases and clarifies the 'since' shorthand ('7d', '30d', '3m', '1y') which the schema already documents, so it adds marginal value beyond the schema.

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

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

The description opens with multiple natural-language examples ('What's new with X', 'latest on Y') and then explicitly defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly names the resource (company change feed) and distinguishes from sibling entity_profile by stating 'Use entity_profile instead when you want the static profile... regardless of window.'

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

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

The description provides concrete query patterns and explicitly states when to use an alternative ('Use entity_profile instead when you want the static profile'). It also details fallback behavior among sources (GDELT preferred, GNews when rate-limited) and notes the USPTO soft-fail condition, giving the agent clear decision 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?

Adds significant context beyond annotations: describes key-value scope by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions, and cross-session reuse. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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 4 sentences and front-loaded with the core action. Every sentence contributes: purpose, when to use, storage details, and related tools. No fluff or redundancy.

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

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

For a simple two-parameter write tool with no output schema, the description covers all essential aspects: main function, triggers for use, persistence semantics, and integration with recall/forget. The lack of return value details is acceptable given the tool's simplicity and the absence of an output schema.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. The description enriches semantics by providing real-world examples (ticker, address, preference) and explaining the key-value pair concept, going beyond the schema's simple type descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes from siblings by explicitly naming recall and forget as complementary tools for retrieval and deletion.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives (recall, forget) and explains persistence differences for authenticated vs. anonymous sessions, covering both when and how to use it.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, returns EDGAR identifiers regardless, labels identifiers with sources, and explicitly lists unresolved identifiers. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and examples, then details supported types and behavior. While it is longer than minimal, every sentence adds value, and the structure is logical. A minor reduction for verbosity in the nested type explanations, but still well-organized.

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

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

Given the tool has only 2 parameters, no output schema, and rich annotations, the description fully covers usage, return behavior (including unresolved identifiers), graceful degradation, and cross-source coverage. It leaves no obvious gaps for an agent to understand what the tool does and how 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 is 100%, but the description adds substantial meaning: for 'type' it explains the full resolution scope (company: cross-source identity with CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand). For 'value' it lists multiple accepted formats (ticker, CIK, ISIN, name) and gives examples. This goes far beyond the schema's brief descriptions.

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

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

The description clearly states the verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers.' It provides concrete examples (ticker, CIK, LEI, RxCUI) and positions itself as the primary tool for name-to-ID conversion ('Use FIRST whenever you have a name but need an ID'), distinguishing it from siblings like compare_entities or 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?

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It details supported types (company, drug) and their inputs, and implies that other tools (e.g., entity_profile) are for subsequent steps. The description also explains that it replaces 2-3 manual lookups, clarifying its role in the tool set.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it 'probes each entity' with ai_visibility_check, implying multiple internal calls, and specifies the output structure ('ranked list with score, confidence, signal density per entity'). This adds valuable context about how the tool behaves without contradicting annotations.

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

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

The description is three sentences with no waste: the first states the purpose, the second explains the process and ranking, and the third gives a concrete use case. It is front-loaded and 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?

Given that there is no output schema, the description adequately explains the return values (ranked list with score, confidence, signal density) and the underlying probe behavior. It also anticipates the user's likely question and use case, making the description self-sufficient for a tool of this complexity.

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

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

The schema already provides 100% description coverage for all parameters, including the role of the first entity as the 'subject.' The description's phrase 'your brand + N competitors' restates schema content without adding new parameter-level detail, so it meets the baseline but does not significantly enhance parameter understanding.

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

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

The description clearly states the specific action ('Compare AI visibility across multiple entities side-by-side'), names the resource (AI visibility), and distinguishes from the sibling ai_visibility_check by focusing on multi-entity comparison. It also details the ranking and output behavior, leaving no ambiguity about what the tool does.

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

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

It provides an explicit use case ('competitive AI-marketing audits') and an example question ('does Claude know about us as well as our competitors?'). It references ai_visibility_check as the underlying probe, implying this is for multi-entity comparison while ai_visibility_check handles single entities. However, it does not explicitly state when not to use this tool or name alternative comparison tools like 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 already establish read-only and idempotent behavior. The description adds substantial behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement on a new version may take 5-30s, and sources_failed will list timeouts while the rest still returns. 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 a one-sentence summary, then flows into usage guidance, return fields, and limitations. Every sentence adds value—no filler or repeated schema info. It is concise despite covering multiple details.

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 composite tool with no output schema, it fully enumerates the returned summary block fields, mentions per-advisory details, links, and alternative versions, and explains failure modes and ecosystem limits. This is more than enough for an agent to understand expected behavior and outcomes.

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

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

Schema coverage is 100% with clear descriptions for both package (including scoped packages) and version (defaults to latest). The description adds context around the composite check but does not introduce new parameter semantics or constraints beyond what the schema already provides, 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 opens with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call.' It names both data sources (deps.dev, bundlephobia) and the exact aspects checked (license, advisories, bundle size, etc.), making the purpose unmistakable and differentiating it from a direct version lookup.

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

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

It provides explicit when-to-use guidance: 'Use whenever an agent asks "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.' This is a model example of 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?

Annotations already convey read-only, open-world, idempotent, and non-destructive behavior, so the safety profile is well covered. The description goes beyond this by specifying the exact return fields (name, summary, record_count, owner/org, url) and the downstream step, adding useful behavioral context.

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

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

The description is two sentences with no filler. The first sentence front-loads the action and resource, and the second provides return value details and actionable next steps. Every sentence adds value, making it highly concise and well-structured.

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

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

For a simple discovery tool with three optional parameters and no output schema, the description sufficiently explains what is returned and how to proceed. It gives the domain scope (Town of Cary GIS) and examples of dataset types, leaving no critical gaps for the agent to choose and invoke the tool.

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

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

The input schema already provides descriptions and examples for all three parameters with 100% coverage. The description does not add additional parameter-level detail beyond what is in the schema; it only gives a sample query ('parcels') which is already present in the schema examples. 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: 'Search' with a specific resource: 'Town of Cary GIS open geospatial datasets' by keyword. It explicitly distinguishes itself from sibling tools by noting that the returned Feature Service url should be passed to query_layer / layer_info, establishing a different role.

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 concrete guidance by saying 'pass that url to query_layer / layer_info,' which implies this tool is for discovery before data access. It doesn't explicitly state when not to use it, but the mention of alternatives provides context for selecting this tool versus its siblings.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses detailed behavior: returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K char cap with truncation flagged. This provides substantial context that annotations alone do not cover, and it does not contradict any 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?

The description is compact yet information-dense: the first sentence establishes the core purpose, the second clarifies when to use it and benefits, and the third adds technical implementation details and limits. Every sentence contributes value 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?

Despite having no output schema, the description explains the return format (top-N passages with character offsets and similarity scores) and covers usage context, technical limitations, and a sibling pairing. For a tool of this complexity, the description is fully sufficient to guide invocation and interpretation of results.

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

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

Schema coverage is 100%, so the schema already documents text, query, and limit with descriptions including defaults and examples. The tool description adds some framing (e.g., 'text you already pulled') but does not materially extend the parameter semantics beyond what the schema provides. 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 performs semantic search inside a fetched record, with the verb 'search' and the resource 'a fetched record'. It distinguishes itself from siblings like search_datasets by specifying it operates on text the agent has already pulled, and includes examples of input and output. This is a specific and unambiguous 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 gives an explicit 'Use when' scenario: when the record is too big to cram into the prompt. It also mentions pairing with ask_pipeworx_grounded, which signals a complementary workflow. It lacks an explicit 'when not to use' or direct alternatives, but the provided context clearly implies 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?

The description discloses rich behavioral details beyond the annotations: phone verification requirement, 10/day SMS cap, webhook HMAC signing with a one-time secret, auto-disable after 10 consecutive failures, and the always-on feed behavior. These operational traits are not present in the annotations and significantly aid an AI agent in anticipating side effects and constraints.

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

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

The description is lengthy but well-organized: purpose, return value, auth, then types and delivery channels in a logical flow. Every sentence carries substantive information without fluff, but the density may be slightly high for quick scanning. The front-loaded core statement compensates for the length.

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

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

Despite lacking an output schema, the description covers creation behavior, return id, webhook secret handling, feed access via recent_alerts, and failure quirks (auto-disable). For a complex subscription tool with nested objects and multiple modes, this is a complete and self-sufficient description.

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 documents all parameters, but the description adds semantic depth for type-specific parameters (e.g., sec_8k items codes and examples like 'items:["5.02"] = officer change') and clarifies delivery constraints (e.g., SMS phone verification, cap). This goes beyond the schema's baseline, making parameter usage more actionable.

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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also states the return value (new subscription id) and distinguishes from sibling tools by enumerating supported event types and delivery channels, making the tool's function unmistakable.

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

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

The description provides clear context for when to use the tool, including the auth prerequisite (Pipeworx OAuth account) and an explicit link to a sibling tool ('pull via recent_alerts') for consuming the feed. It does not fully articulate 'when not to use' or alternative tools for every scenario, but the usage context is well-defined.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it returns category-bucketed example questions drawn from a live catalog of thousands of tools, and that each example includes the exact tool and argument shape. This goes beyond the annotations and helps set expectations for variability and scope.

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

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

The description is detailed but well-structured, beginning with user-facing question examples, then describing the output, parameter behavior, and usage context. Every sentence contributes, though the initial slash-separated question list is slightly redundant with the rest of the description.

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 adequately explains the return value (category-bucketed example questions with tool+argument shapes). It covers when to use, parameter semantics, and even names related meta-tools to learn. This is complete for an optional-parameter onboarding tool with strong annotations.

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

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

Schema coverage is 100% and the schema's parameter description already explains the optional topic and its possible values. The description reinforces this by noting 'Call with no arguments for the full spread' and 'pass topic to focus', but does not add meaningfully new information 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 this tool is the onboarding entry point for discovering what Pipeworx can do, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by focusing on suggested example questions and learning meta-tool calls, rather than direct queries or tool 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?

Explicitly says 'Use this FIRST' when you don't know what Pipeworx can do, or to learn how to call meta-tools. It also gives clear guidance on calling with no arguments for full spread or passing a topic to focus, with examples like 'finance', 'pharma', 'betting'.

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

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

The description goes beyond the annotations by disclosing that ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via 'recent_alerts'. This adds meaningful behavioral context that annotations alone don't provide.

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

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

Two tightly written sentences convey the action, ownership, deactivation semantics, and historical retention with no redundant wording. The information is front-loaded and well-structured.

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

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

For a simple one-parameter idempotent cancel operation, the description covers purpose, ownership, non-destructive behavior, and side effects. It doesn't mention return values or invalid-id handling, but these are not critical for this tool's use case.

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

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

The input schema fully describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe' (100% coverage). The description adds nothing beyond 'by id', so it doesn't enhance parameter 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 uses a specific verb ('Cancel') and resource ('subscription'), clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It also clarifies the exact effect (deactivation vs. deletion), making the purpose unambiguous.

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

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

The description conveys a clear usage context: cancel a subscription by id, with an ownership restriction (only own subscriptions). It does not explicitly list alternatives or when-not-to-use scenarios, but the simple nature of the tool makes the intended use obvious.

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

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

The description goes well beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) by disclosing specific behavioral traits: the two verification pathways (SEC EDGAR fast path vs grounded pipeline), the possible verdicts, and the meaning of 'could_not_verify' (an infrastructure failure, not evidence). This adds crucial context for the agent to 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 dense but every sentence carries important information: examples, routing logic, verdict list, caller caveats, and efficiency statement. It is well-structured with clear sections and avoids fluff. The length is appropriate for the tool's complexity.

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

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

Given the tool has no output schema, the description thoroughly explains return values (verdicts, actual value with citation, reasoning) and error handling ('could_not_verify' carries verification_error). It also covers the fallback behavior for different claim types. This is complete for the agent to invoke and interpret 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?

Even though the input schema already provides 100% coverage, the description adds meaningful semantic detail beyond the schema. For 'tolerance_pct', it explains how it overrides the implied tolerance, its effective range (0.5–50), and its practical use case (hallucination detection). For 'claim', it gives realistic examples. This enriches the agent's understanding of how to set parameters.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides multiple example phrasings ('Is it true that…', 'fact check', 'verify the claim that…'), specifies the resource (authoritative sources), and distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance (company-financial claims vs any other factual claim) and clarifies important nuances like the difference between 'could_not_verify' and 'unsupported.' This is strong usage guidance with no ambiguity.

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