Arcgis Peachtreecorners

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

Annotations already cover read-only, open-world, idempotent, non-destructive. The description adds valuable context: the default model (Workers AI Llama-3.3-70b, free), the BYO-key cost implication for Anthropic, and the per-model return structure. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core action and outcome, then details on default/cost, then return format and use cases. Every sentence contributes value with no redundancy.

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

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

Despite having no output schema, the description explicitly states the return structure (per-model {score, confidence, signals, raw_response} + combined view), explains the default model and cost implications, and gives use cases. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context for the `_apiKey` parameter (cost/payment) and the default model, which complements the schema but does not significantly expand parameter semantics beyond what the schema already states.

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

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

The description clearly states a specific action ('Probe one or more LLMs') with a concrete resource (business/brand/product/topic) and an output (visibility score 0-100 per model). It distinguishes itself from siblings by focusing on visibility scoring across models, and mentions the return structure.

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

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

Provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state exclusions or alternatives, but the use cases are sufficient to guide when to use this tool.

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

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

Annotations already cover read-only and idempotent hints. The description adds context about routing to 5,564 tools, filling arguments, and returning citation URIs. It also subtly notes the lack of verbatim evidence compared to the grounded variant. 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 densely informative, with a clear front-loaded directive, examples, and escalation paths. Minor redundancy ('START HERE' and 'default entry point') 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 complexity (5,564 tools, broad domains) and absence of an output schema, the description is thorough. It explains return characteristics (citation URIs), when to use, when to step up, and provides examples, covering all essential context.

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

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

Schema covers all parameters with alias descriptions (100% coverage), so baseline is 3. The description enriches this by providing concrete example questions and clarifying the natural-language scope, adding value beyond the schema.

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

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

The description uses specific verbs ('routes', 'returns') and clearly states the resource (structured answers with citation URIs). It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the tool's 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?

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'Step up only when needed' with alternatives for grounded and deep research. Includes both inclusion criteria and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds important behavioral context beyond that: this is widespread experimental routing ('candidate routing improvements enabled live'), there is zero fallback ('Falls back to nothing'), and its runtime state varies over time (no candidate active currently, retired 2026-07-26). This effectively warns the agent it may be routed through untested logic, which annotations cannot 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 ~90 words across four sentences, front-loaded with the most critical info (beta of a universal router, identical to stable). Each sentence contributes distinct value: identity/equivalence, current state (no candidate), usage guidance, and no-fallback safety. Slightly extended due to the retirement-date detail, but that date grounds the current-state claim and aids trust; no wasted filler.

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

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

This is a high-complexity tool (router over 5,564 underlying tools) with no output schema, but the description covers the essential context: what it is, the current experimental state, explicit usage fallback, and safety profile backed by annotations. A minor gap is that it assumes prior knowledge of what ask_pipeworx means or how the router responds (no mention of answer format, latency, or citation behavior), but for a question-to-router tool the coverage is strong enough.

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% - all six parameters (question and 5 aliases) are documented in the input schema, including the aliases note. The description contributes 'same arguments' but adds no individual parameter meaning beyond the schema. Per the rubric, this is the baseline 3 for high schema coverage; the description correctly does not repeat the schema.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, a universal router with the same 5,564 tools and response shape. It self-identifies against the sibling list (distinct from ask_pipeworx and ask_pipeworx_grounded) by framing itself as the experimental edge of an existing stable router. The verb 'ask/routes' and resource (universal router) are specific and non-tautological.

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

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

The description explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the evaluation workflow ('results are compared against the stable router to decide what merges') and clarifies current behavior (matches ask_pipeworx exactly since no active candidate). This is near-ideal when/why guidance with an implicit contrast to the stable sibling.

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

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

Beyond annotations, the description details return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and explicit refusal reasons. It also discloses cost ('extra LLM call') and data-scoping constraint ('using ONLY what the tool result contains'). No contradiction with readOnly/idempotent hints.

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

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

Every sentence carries functional information: purpose, process, return structure, use cases, cost comparison. Despite length, it remains tight and 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?

The description covers success and failure modes, output fields, refusal reasons, use cases, and cost trade-off. Without an output schema, this level of detail makes the tool self-contained.

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

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

Schema already documents the 'question' parameter and all aliases; description adds no additional parameter-level detail. With 100% schema coverage, 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing, fetching, and extracting answers. It distinguishes from sibling 'ask_pipeworx' by emphasizing grounded extraction and explicit refusals.

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 whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' Provides both when-to-use and when-not-to-use, naming 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?

Beyond the readOnly/idempotent/openWorld annotations, the description discloses extensive runtime behavior: parallel fan-out, resolver confidence fields, low-confidence short-circuit with status, market-closed detection, wide-spread tradeability flag, cancellation-rule parsing (refund_50_50, resolves_no_on_cancel, etc.), news fallback fields, and the blocking nature of both failure routes. This far exceeds the annotation baseline.

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 actionable detail. It uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) which makes scanning easy. Every sentence adds value, though some redundancy exists between the fan-out examples and the resolution-rule discussion. It earns a 4 for appropriate completeness without being bloated.

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

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

For a complex tool with no output schema, the description covers all essential aspects: input formats, classifiers, fan-out behavior, response shapes, resolver confidence contract, parent-event extraction, news fallback mechanics, safety statuses, and cancellation-rule edge cases. This is sufficient for an agent to invoke the tool and correctly interpret results across many 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces the market parameter's flexibility (slug/URL/text) but does not add new syntax or format details beyond the schema. The depth and include_raw parameters are already well-documented in the schema, and the description's fan-out examples illustrate behavior rather than parameter semantics.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this tool from siblings like ask_pipeworx or deep_research by focusing on Polymarket bet resolution with category-specific data fan-out, and explicitly lists the input types (slug, URL, or question text).

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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides behavioral guidance like 'ALWAYS inspect these before trusting the analysis block' and explains blocking paths for low-confidence/closed markets. It doesn't explicitly state when to use an alternative tool, but the use cases are specific enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial context: it details the exact data fields pulled for companies (revenue, net income, cash, long-term debt) and drugs (FAERS counts, FDA approvals, trials), notes correct handling of off-calendar fiscal years (e.g., AAPL, NVDA), and mentions result sorting and citation URI returns. This goes far beyond the annotations and enriches the agent's understanding of behavior.

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

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

The description is dense yet well-organized: it starts with trigger examples, states the primary use case, then provides type-specific details and output behavior. Every sentence conveys actionable information without filler. The structure is logical and front-loaded, making key points immediately visible. Despite its length, it 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 no output schema, the description compensates by stating that results are sorted by primary metric, returns paired data, and provides citation URIs. It covers the main facets: entity count, data sources, metric selection, off-calendar handling, and output ordering. This is comprehensive for a comparison tool, leaving minimal ambiguity about what the tool returns and how the agent should interpret 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?

The schema covers both parameters (type and values) with types, enums, and descriptions. The description adds further semantic meaning: it explains the enum values in detail (what each type pulls) and gives concrete examples for values (tickers vs drug names). It also conveys constraints (2-5 items) and the implication of parallel processing. This adds value beyond the schema, which already had 100% coverage, so a high score is warranted.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from single-entity lookups by emphasizing a parallel call and lists specific data sources (SEC EDGAR/XBRL, FAERS). This goes beyond a generic verb and resource, providing specific scope and differentiating from siblings like entity_profile.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and gives example queries. It also clarifies when to use type='company' vs type='drug', and explains the output ordering. This is a clear directive with alternatives explicitly mentioned, making it easy for an agent to choose this tool over others.

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 no destructive action. The description adds substantial context beyond this: it never invents data (gaps[]), citations are always fetchable, large records are semantically excerpted, timing expectations (15-90s), and contradictions[] behavior. It also clarifies the paid tier requirement for depth:'thorough'. 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 but dense, with every clause delivering critical operational details: authentication, fallback tool, source scope, output packet structure, depth semantics, timing, and edge-case behavior. It is front-loaded with the most immediate action item (account required) and uses clear contrasts. Slight redundancy in repeating 'findings packet' details but overall each 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 the tool's complexity (2 params, no output schema, rich behavior), the description fully covers return values (findings packet, gaps[], contradictions[], hop field, citation_uri), usage constraints (account, paid depth), performance expectations, and exception handling (excerpting, never invented). It equips an agent to select and invoke correctly, and even provides fallback alternatives.

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 documents both parameters well. The description adds meaningful nuance: explains the exact facet counts for each depth ('quick=3', 'standard=3', 'thorough=6'), the paid requirement for 'thorough', and that the question field accepts broad/multi-part natural language. This enriches the schema's baseline.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, with specific verbs like 'research' and 'decomposes.' It distinguishes from siblings by explicitly contrasting with ask_pipeworx and noting 'this is NOT open-web search.'

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx' and for breaking/current-news topics prefer ask_pipeworx. Also includes account requirements and fallback instructions for unsigned-in users.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context beyond that: it explains the return format (top-N tools with names, descriptions, full input schemas, curated examples) and that results are directly callable without a second lookup. No contradiction with annotations.

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

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

Three sentences, each earning its place: what it does, when to use, and what it returns. The structure is front-loaded with the action verb, and the domain list is compact yet comprehensive. No waste.

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

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

For a discovery tool with no output schema, the description fully covers the essential context: purpose, usage timing, return format, and readiness of results. It even mentions the limit behavior in the schema. 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 input schema has 100% coverage, with clear descriptions for query (including examples) and alias parameters, plus limit. The tool description does not add extra meaning beyond the schema, and the schema is sufficient, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Find tools by describing the data or task.' It distinguishes itself from siblings by positioning as a meta-discovery tool, listing broad domains (SEC filings, FDA drugs, etc.) and explicitly saying to 'Call this FIRST.'

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It implies when-not via 'not just one answer' but does not name specific alternative tools or exclusion cases, 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 mark it read-only and non-destructive, but the description adds rich behavioral context: fans out across multiple sources, returns specific fields, details about USPTO PatentsView API sunset and soft-fail, GDELT→GNews fallback, and limits like 'up to 5' filings. No contradiction with annotations.

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

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

The description is dense but well-structured, starting with user-intent examples, then the core purpose, followed by fan-out details and limitations. Every sentence adds value, and it avoids unnecessary fluff despite its length.

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

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

With no output schema, the description thoroughly explains return values (CIK, filings, fundamentals, patents, news, LEI), fallbacks, and usage limitations. It is complete for a complex tool with multiple data sources.

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

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

Schema already covers both parameters with 100% coverage, including the enum and format. The description adds concrete examples ('AAPL' or '0000320193') and reinforces the name limitation, going 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 states the tool's purpose with specificity: 'full cross-source profile of a US public company in ONE parallel call.' It provides several example queries and explicitly contrasts with chaining single-pack lookups, distinguishing it from related tools like resolve_entity.

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

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

It gives explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it (names not supported, use resolve_entity first), clarifying 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds rationale (clearing sensitive data) and the 'previously stored' nuance, but doesn't detail irreversibility or behavior on missing keys. It neither contradicts nor heavily enriches 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?

Two sentences, front-loaded with the action, and each sentence earns its place. The pairing note with remember/recall is concise and adds practical guidance without fluff.

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

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

The tool is simple with one required parameter and clear annotations. The description fully covers purpose, usage, and relationships to sibling tools. No output schema is needed, and the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description's 'by key' adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings like remember (store) and recall (retrieve), making its purpose unambiguous.

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

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

The description provides explicit use cases: when context is stale, task is done, or clearing sensitive data. It also mentions pairing with remember and recall. It lacks explicit 'when not to use' but gives solid situational 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 and idempotentHint, but the description adds crucial behavioral context: it 'Fetches the page' (external network call) and outputs 'a single text blob ready to drop at site-root/llms.txt'. This goes beyond the annotations by revealing the fetch operation and exact output format, which is valuable for an agent.

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

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

The description is three sentences, front-loaded with the primary action and purpose, followed by process and concrete use cases. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's simplicity, the description covers purpose, process, output format, and practical use cases. The schema handles parameters, annotations cover safety/idempotency, and the description explains what the return value looks like ('standard llms.txt markdown format'), making it complete for an agent.

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

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

The input schema has 100% description coverage for both parameters (url and max_links), so the baseline is 3. The description reinforces the URL's role ('fetches the page') and hints at link extraction, but does not add new parameter-level detail beyond the schema. It is sufficient but not exceptional.

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

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

The description starts with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from all siblings by naming its unique output (llms.txt) and the exact process (fetch, extract, emit standard markdown). This is more specific than the title alone.

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: 'Useful for: 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 does not mention alternatives or exclusions, but the scenarios are explicit enough to guide when to invoke this tool over others.

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 behavioral context by specifying the exact schema elements returned (fields name+type, geometry type, record count, capabilities), which goes beyond the annotations and clarifies what the tool produces. No contradictions.

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

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

The description is a single, front-loaded sentence that covers all essential information without waste. Every clause 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?

With no output schema, the description compensates by explicitly listing the returned elements (fields, geometry type, record count, capabilities). Given the simple 1-param input and strong annotations, this is sufficient for correct tool 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 description coverage is 100% for the single 'url' parameter, which already explains its format (Feature/Map Service layer url). The tool description simply repeats 'by url' without adding new syntax or constraints, so it adds minimal 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 uses a specific verb ('Get') and clearly identifies the resource (ArcGIS Feature/Map Service layer's schema) plus the exact data returned (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like query_layer, which would execute queries rather than describe schema.

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

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

The description implies usage when you need a layer's schema, but it does not explicitly state when to use this tool over alternatives such as query_layer. There are no exclusions or alternative tool references, so the guidance is only implicit.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by specifying the exact return fields (id, type, params, created_at, etc.) and clarifying that 'active' subscriptions are returned by default, which is not covered by 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 long, with the first sentence covering purpose and return fields, and the second providing usage guidance. There is no redundancy or fluff; every word earns its place.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete: it states scope, return fields, default behavior, and usage guidance. The absence of an output schema is mitigated by listing the return fields directly.

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

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

Schema coverage is 100% for the only parameter (include_inactive) with a clear description in the schema itself. The tool description does not add any additional semantic detail for this parameter, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('List the caller's active subscriptions') and differentiates from sibling tools like subscribe/unsubscribe by focusing on the listing aspect. It also explicitly lists the returned fields, making the purpose unambiguous.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use it, though it does not directly name the alternative tools (subscribe/unsubscribe), relying on strong implication from the sibling list.

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

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

Discloses rate limiting ('5 per identifier per day'), that it is free and doesn't count against quota, the daily digest cadence, and the claim_token return/retrieval behavior. These add context beyond the annotations, which are all false and offer no behavioral insight.

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

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

Though ~170 words, every sentence earns its place: purpose, use cases, exclusions, follow-up, rate limits, and cost are packed efficiently without redundancy. The most critical info is front-loaded.

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

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

Given no output schema, the description covers return behavior (claim_token, status/changes on follow-up), handles all four parameters implicitly via usage guidance, and includes constraints (rate limit, quota). It is fully self-contained for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructing users to frame feedback in terms of Pipeworx tools/packs, which relates to the context parameter.

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

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

The description opens with a precise verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings like ask_pipeworx by framing this as a feedback channel for the Pipeworx connection's own tools, not a general Q&A tool.

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

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

Explicit when-to-use categories are given (bug, feature/data_gap, praise) and a definitive when-not case: tools from other MCP servers should be reported to that server instead. It also provides usage constraints like 'don't paste the end-user's prompt' and explains the claim_token follow-up flow.

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 and non-destructive. The description adds that the signal is 'derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window,' giving the agent crucial context about data source and freshness beyond the annotations.

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

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

The description is moderately long but well-structured, with a clear statement, a bulleted use-case list, and a closing note on caching. Every sentence contributes to the agent's understanding, though the 'Self-aggregating signal' phrase is stylistic.

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

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

For a simple read-only tool with one parameter, the description conveys purpose, use cases, and relevant behavioral caveats. It doesn't detail the return payload structure, but since there's no output schema, the high-level return list is sufficient.

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

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

The schema already includes a full description for the window parameter, including defaults and trade-offs, so the description adds little beyond what's structured. With 100% coverage, a baseline of 3 is appropriate.

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

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

The description opens with a concrete question and then states 'Returns the top tools, top packs, and total call volume over a recent window.' This clearly identifies the operation and its output, distinguishing it 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 lists three explicit use cases with 'Useful for:' and elaborates on the window parameter semantics. It doesn't explicitly name alternative tools or when-not to use, but the use-case framing provides clear guidance.

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

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

Annotations already declare read-only/idempotent, but the description adds critical behavioral context: Jaccard similarity threshold, placeholder partition filter, and the fill_check warning that realizable_edge_pp ≤ 0 means the signal is not tradable. No contradiction with annotations.

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

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

The description is long but front-loaded with purpose and usage, and every sentence adds value (e.g., fill check, semantic anchor). It could be slightly tightened, but the length is justified by the tool's complexity and the absence of an output schema.

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 explicitly lists response fields (opportunities[], partition_check) and explains the fill_check behavior and edge cases (thin legs, low similarity). It also points to polymarket_fill_risk for sizing, covering the tool's full behavioral footprint.

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

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

Although the schema covers both parameters, the description adds concrete slug examples ('fed-decision-may-2026'), explains the different processing for event vs topic, and details what each mode returns. This goes well beyond the schema's one-line 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 clear verb+object ('Find arbitrage opportunities on Polymarket') and specifies the detection methods (monotonicity violations + partition-sum checks). It distinguishes itself from sibling tools like polymarket_edges by focusing on arbitrage and clearly naming two modes (event/topic) that define its scope.

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

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

It explicitly tells when to call with no args, event, or topic, and explains the difference between single-event and cross-event scanning. It also names the alternative tool polymarket_fill_risk for custom sizing, giving clear when-not-to-use guidance.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing internal model families, response segment structure, edge computation after slippage, Kelly caps, 24h-move warnings, diagnostics for empty segments, Fed bet exclusion rationale, and 1-hour KV caching. This is exemplary 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 long, but every section (purpose, model families, response structure, knobs, diagnostics, caching) earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with the core purpose, though the single dense paragraph and slight redundancy in Kelly details prevent 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?

Without an output schema, the description thoroughly documents the top-level response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, 24h warning), and even explains why Fed bets are excluded. This gives an agent everything needed 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?

Schema description coverage is 100% with highly detailed parameter descriptions, including the nuanced behavior of min_partition_leg_kelly. The tool description only summarizes the knobs without adding new semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly frames the tool as a discovery mechanism for betting opportunities, distinguishing it from likely siblings like polymarket_edge_tracker or polymarket_fill_risk.

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

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

It provides clear usage context ('Built for "what should I bet on today"') and explains how knobs filter opportunities. However, it does not explicitly mention sibling tools or state when NOT to use this tool in favor of an alternative, so it falls short of the highest 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?

Annotations already indicate readOnly/ idempotent, but the description adds valuable behavior: 60-day TTL limits history, decay computed from daily closes, snapshot gaps mean no scan occurred. This goes well beyond the annotations without contradicting them.

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

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

The description is long but every sentence carries useful information: purpose, response structure, limitations, and parameter meaning. It is front-loaded with the core value proposition and structured with clear sections.

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 telemetry tool with no output schema, the description fully explains the response shape (tracked, expired, snapshot_dates), the meaning of fields, and the limits. The agent has enough to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats defaults and window family but does not add syntax or format details beyond the schema. It does add context about how days and window affect the response, but that is marginal.

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: edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('answers') and resource ('polymarket_edges snapshots'), and differentiates from siblings like polymarket_edges by focusing on the how-long/decay angle.

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 strong usage context: it explains the difference between a fresh wide edge and an old one, implying when to use this tool. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds extensive behavioral detail beyond that: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and highlights forced_directional_risk. It also explains the subtle risk of partial basket fills converting an arb into a directional position. 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 it is structured into clear sections (SINGLE-MARKET and BASKET) with a logical flow from inputs to outputs to usage recommendations. Every sentence conveys either a functional detail, a return value, a constraint, or a risk warning—no filler. Given the tool's complexity, this length is appropriate and well-organized.

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

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

With no output schema, the description must explain return values, and it does so comprehensively: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also covers both usage modes and their prerequisites. This is a complete picture for an AI agent to decide and invoke correctly.

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

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

Although the input schema already has 100% parameter coverage, the description enriches every parameter with mode-specific semantics. For example, size_usd is clarified as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode, and it adds the default (1000) and clamp range (10–1,000,000). The `side` parameter's auto-detection in basket mode is also explained. This goes well 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 a specific, action-oriented statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and execution quality rather than opportunity discovery. It also enumerates distinct modes (single-market and basket), 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?

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why—theoretical overround on thin books is not capturable and partial fills cause unhedged directional risk. This provides both a clear usage trigger and a rationale, exceeding typical 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?

Exceeds annotation coverage: readOnlyHint and idempotentHint are already present, but the description reveals critical behavioral traits including response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and diagnostic counters (skipped_cross_type/subtype). It also discloses limitations like 'pre-mapped ≠ tradeable' and when the spread is 'mathematically meaningless', giving the agent deep understanding of edge cases.

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

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

The description is long but every sentence carries information: it covers purpose, two modes, response format, safety fields, and caveats. It is front-loaded with the core purpose. Slightly verbose compared to minimal two-sentence descriptions, but the complexity of the tool justifies the length and it remains well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS).

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

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

Even without an output schema, the description fully explains the response shape (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type) and edge cases. It covers the three parameters, the logic behind matching, and what makes the spread valid or invalid. This is a complete description for a complex cross-venue tool with no 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?

The schema already documents all three parameters with 100% coverage, establishing a baseline of 3. The description adds meaningful semantics beyond the schema: it explains the two modes, how topic auto-fetches the event on each venue, how explicit tickers/slugs override the mapped side, and includes concrete examples ('fed', 'btc', 'KXFED-26OCT'). This clarifies parameter combinations and default behavior.

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 clear, specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains the core distinction from potential siblings by focusing on cross-venue comparison and even quantifies the typical spread (2-25pp), which uniquely identifies its purpose.

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

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

The description provides explicit when-to-use guidance: it names two modes (topic shortcuts vs explicit tickers), when each is appropriate, and when the output is not meaningful (compatibility_warning conditions, temporal misalignment). It also warns that most pre-mapped topics are not tradeable. However, it does not explicitly name alternative tools as exclusions, only implies that this is the tool for cross-venue spread analysis.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by disclosing what the tool returns ('attribute rows (and geometry)') and the supported query options (SQL-like where, pagination). This goes beyond the annotation safety profile without contradicting it, meriting 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 two sentences, front-loaded with the core purpose, and every clause earns its place. The first sentence states the action and parameters; the second provides a concise sampling tip. No filler or redundant repetition of schema 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?

Despite lacking an output schema, the description covers the return type (attribute rows and geometry), the source of the URL (search_datasets), the key parameters, and a usage pattern. Given the annotations and full schema coverage, this is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains the SQL-like nature of 'where', the comma-separated format for 'out_fields', and gives a concrete usage example. This practical guidance helps the agent select and combine parameters correctly.

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 ('Query') and resource ('ArcGIS Feature Service / Map Service layer'), and states the input (url from search_datasets). It clearly distinguishes this tool from siblings by specifying the SQL-like query capability and returning attribute rows with geometry, 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?

It specifies that the URL should come from search_datasets and provides a practical sampling idiom ('where="1=1" + out_fields="*"'). This gives clear context for when to use the tool, though it does not explicitly name alternative tools or exclusion conditions, which prevents a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond these: scoping to the caller's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys by omitting the key argument. This is useful context not present in annotations, though the description does not cover not-found behavior or return format.

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

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

Three concise sentences, front-loaded with the action. Each sentence adds distinct value: what it does, when to use, and how it pairs with siblings/scoping. No wasted words.

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

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

For a simple one-optional-parameter tool with strong annotations, the description covers purpose, usage, scoping, and complementary tools. It is complete enough for an agent to invoke correctly. A longer description would be overkill.

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

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

The schema provides 100% coverage for the single `key` parameter, including its description 'Memory key to retrieve (omit to list all keys)'. The description restates this behavior and gives usage examples in the schema, but adds no new syntax or format details. Baseline of 3 is appropriate since the schema carries the parametric load.

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

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

The description starts with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes this from sibling tools by explicitly naming remember and forget. The purpose is unambiguous and action-oriented.

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

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

Provides explicit usage context: '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 delineates complementary tools: 'Pair with remember to save, forget to delete.' This tells the agent when and how to use the tool relative to 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?

Annotations already establish read-only and idempotent behavior, and the description adds the important side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also discloses the persisted feed nature and provides the raw payload fields, which goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary verb, and every sentence adds value: purpose, filtering, side-effect, polling, and an external alternative. No redundant or filler content.

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

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

Despite lacking an output schema, the description enumerates the return fields (source, citation_uri, raw event payload) and explains all key options. The combination of annotations (readOnly, idempotent, non-destructive) and the description's coverage of filters, mark_read, and polling makes it a complete guide for 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%, but the description adds meaning by giving a concrete type example (sec_8k) and clarifying that 'since' is an ISO timestamp. It also explains the consequence of mark_read, which is not fully captured in the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which names the exact action and resource. It further clarifies the content ('alerts the evaluator has written to your persisted feed') and distinguishes it from sibling tools like list_subscriptions and recent_changes by focusing on alert events.

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 gives practical guidance: 'Filter by type... and/or since...' and 'Polls work fine,' which signals polling suitability. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) but does not explicitly contrast with sibling tools, so it lacks exclusions but provides clear 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?

The description discloses the fan-out to multiple sources, fallback logic (GDELT preferred, GNews when rate-limited/5xx), USPTO soft-fail due to API sunset, and the return shape (changes[] grouped by source, total_changes, citation URIs). Annotations already declare read-only/idempotent, and the description adds substantial context without contradiction.

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

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

The description is dense but every sentence earns its place: it opens with user-intent examples, lists sources, explains fallbacks, parameter syntax, and output structure—all in a compact paragraph with 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?

Despite having no output schema, the description fully explains what the tool returns ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers edge cases like source fallbacks and USPTO soft-fail, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description goes beyond by explaining `since` accepts ISO or relative shorthand with examples ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also clarifies `value` can be a ticker or zero-padded CIK, adding guidance not fully explicit in the schema.

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

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

The description clearly states it provides a 'change feed for a company in the last N days/weeks/months' with specific sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes itself from the sibling tool entity_profile by contrasting dynamic changes vs static profile.

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

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

The description gives concrete example queries like "What's new with X" and "updates on Acme", and explicitly says to use entity_profile instead for static profile needs, providing clear when-to-use vs when-not-to-use guidance.

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

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

Beyond annotations (idempotent, not read-only, not destructive), the description adds key behavioral context: memory is scoped by identifier, authenticated users get persistent storage, anonymous sessions retain data for 24 hours. This is valuable and doesn't 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 three sentences, front-loaded with the main action, then usage context, then key persistence details. Every sentence adds value, with no wasted words or repetition.

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

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

For a simple two-parameter write operation with no output schema, the description is fully complete: it explains the purpose, when to use, persistence behavior, scoping, and how it relates to sibling tools (recall and forget). No significant gaps remain.

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 complete parameter descriptions with examples for both 'key' and 'value', covering 100% of parameters. The description doesn't add parameter-level detail beyond what the schema offers, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It also distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference.' It also names the alternative tools (recall, forget) for complementary operations.

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

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

Beyond the annotations (readOnlyHint, idempotent, openWorld), the description discloses graceful degradation: 'LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return.' It also states that unresolved identifiers are listed explicitly under 'unresolved' rather than omitted, and that internal cascading replaces manual steps. 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 adds distinct value: examples, guidance, supported types, behavior notes, and a summary of internal cascading. It is front-loaded with user-facing examples and the critical 'Use FIRST' directive. There is no fluff or redundancy; each 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 the tool has no output schema, the description fully compensates by explaining return structure: identifiers labelled with sources, explicit 'unresolved' list, graceful degradation. It covers both entity types (company and drug) with sufficient detail. The complexity (2 required params, cascading lookups, multiple sources) is fully addressed.

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 the description adds substantial meaning: for the 'value' parameter it provides numerous examples (ticker, CIK, ISIN, brand/generic name) and explains ISIN-to-LEI mapping. For 'type' it details what identifiers are returned for company (CIK, ticker, LEI, FIGI) and drug (RxCUI, ingredient). This goes far beyond the minimal 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 begins with concrete examples like 'What's the ticker for…' and states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly says 'Use FIRST whenever you have a name but need an ID,' which clearly distinguishes this tool from its many siblings (e.g., entity_profile, compare_entities) that work with known IDs.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It implies when not to use (when you already have an ID) and explains that this tool replaces 2-3 manual lookups, giving a concrete use case. No other tool in the sibling list offers this name-to-ID resolution, so the differentiation 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 and idempotentHint=true; description adds meaningful behavior: 'Probes each entity ... with ai_visibility_check' (tool dependency) and 'Returns ranked list with score, confidence, signal density per entity', which goes beyond safety annotations. Not contradicted, and adds useful 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?

Three concise sentences: purpose, use case, and return value. Each sentence earns its place, front-loaded with the core action and no filler words.

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

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

Given no output schema, the description sufficiently explains the return structure (ranked list with score, confidence, signal density). It also describes how it operates (probes with ai_visibility_check) and the typical use case, making it complete for a comparison 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 covers all 4 parameters with descriptions (100% coverage), so baseline is 3. The description does not add syntax, format, or additional meaning beyond what schema already provides; it only reinforces the 'entities' concept with 'your brand + N competitors'.

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

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

Description clearly states the tool 'Compare AI visibility across multiple entities side-by-side', specifying the resource (AI presence) and action (compare). It distinguishes from sibling ai_visibility_check by focusing on multiple entities, ranking, and identifying most/least recognized, 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?

Provides clear context for use: 'Useful for competitive AI-marketing audits' and implies the alternative by stating it probes with ai_visibility_check. However, it lacks explicit when-not-to-use guidance or named alternatives, so it doesn't fully 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?

The description discloses that the tool fans out to two external services and that partial failures degrade gracefully, with bundlephobia's first measurement potentially taking 5-30s and sources_failed listing timeouts. This adds behavioral context beyond the annotation hints (read-only, idempotent). 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 several sentences but every sentence adds value: core purpose, usage triggers, return fields, ecosystem caveat, and failure behavior. It is structured to front-load the main purpose and then provide necessary detail.

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

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

Given no output schema, the description lists all key return fields (summary block keys) and explains failure modes and timing. It also specifies ecosystem limitations, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema already documents both parameters with descriptions, giving 100% coverage. The description adds that version defaults to the latest published version when omitted, which supplements the schema. This is a minor but useful addition.

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

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

The description clearly states it is a composite check for evaluating whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the exact question it answers ('is X safe / popular / small') and distinguishes this npm-focused tool from sibling tools. The verb 'scan' and resource 'dependency' are explicit.

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

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

It explicitly instructs to use this tool when an agent asks about package safety, popularity, or size. It also states NPM ecosystem only in v1 and directs other ecosystems to deps.dev:version, providing an exclusion and alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds transparency about the returned fields (name, summary, record_count, owner/org, url) and the chaining behavior (pass url to query_layer/layer_info), which goes beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by the return shape and a usage tip. Every sentence serves a purpose with no filler.

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

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

With all parameters optional and well-documented, strong read-only/idempotent annotations, and no output schema, the description sufficiently covers the return values and workflow. It even tells the agent what to do with the returned URL, making the tool self-contained.

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 (query, limit, org_id) fully described. The description only adds 'by keyword', which aligns with the query parameter but does not introduce new semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (Search), target (City of Peachtree Corners GIS open geospatial datasets), and scope (by keyword, with examples like parcels and zoning). It also distinguishes itself from sibling tools by noting the returned Feature Service URL can be passed to query_layer/layer_info, creating a clear workflow.

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

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

The description implies a discovery workflow: search for datasets first, then use the returned URL with query_layer/layer_info. It provides clear context for when to use the tool, though it does not explicitly mention alternatives or 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=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description adds valuable behavioral specifics: it returns passages with character offsets and similarity scores, uses BGE-base-en embeddings, 500-char overlapping windows, and enforces a 200K char cap with truncation flagging. This gives the agent a transparent view of mechanics and limits.

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

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

The description is information-dense yet efficiently structured. It front-loads the core purpose, immediately covers the primary use case, then layers in technical details and a sibling pairing. Every sentence contributes actionable context, and the length is justified by the richness of behavior it explains.

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

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

There is no output schema, so the description must communicate return structure — and it does: 'top-N passages with character offsets and similarity scores.' It also covers input size limitations, truncation behavior, and the recommended integration with ask_pipeworx_grounded. The agent receives enough context to use the tool correctly without external documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces that `text` is the already-fetched document and `query` is natural language, but does not add new parameter-level details beyond the schema's own descriptions and examples. It adds no extra syntax, format, or interplay that would warrant a higher score.

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 'Semantic search INSIDE a fetched record' — a specific verb and resource that immediately anchors the tool's function. It distinguishes itself from sibling tools by explaining it searches within retrieved text rather than acting as a general query interface, and explicitly references ask_pipeworx_grounded as a related but distinct tool.

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

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

The description gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also names an alternative flow ('Pairs with ask_pipeworx_grounded') and explains the intended combination of fetching and grounding. This satisfies the when/when-not/alternatives criterion clearly.

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 meaningful context beyond annotations: OAuth requirement, subscription id return, SMS verification and 10/day cap, and feed always-on behavior. Annotations already indicate a write operation (readOnlyHint false) and non-destructive intent, which the description aligns with; no contradiction.

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

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

Dense and front-loaded with the core purpose in the first sentence. While structured as a single paragraph with several long clauses, it packs essential information without significant fluff. Could be improved with bullets, but remains 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?

Covers authentication, delivery channels (feed, email, sms), and examples for three of five subscription types, but omits patent_grant and clinical_trial from the prose, and does not mention the webhook delivery channel in the description (though schema covers it). This omission could mislead an agent into thinking only three types are supported, leaving a notable gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value with examples like items:['5.02'] meaning officer change and delivery specifics (verified phone, cap), but omits two schema types (patent_grant, clinical_trial) from its list, which slightly reduces its added value.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' and explicitly mentions 'Returns the new subscription id,' clearly defining the verb, resource, and unique output. This distinguishes it from siblings like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides context for when to use (proactive monitoring), prerequisites (requires OAuth account, anonymous + BYO cannot persist), and differentiates from pull-based retrieval by noting the feed is 'always on' and pulled via recent_alerts. However, it does not explicitly name alternative tools or state when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: the tool returns example questions with exact tool+argument shapes from a live catalog, and explains the two modes (full spread vs focused by topic). This goes beyond the annotations and gives the agent a clear model of what to expect.

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

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

The description is dense but well-structured: it opens with example user queries, states the purpose, then describes output, parameter usage, and when to use it. Every sentence contributes new information. It is longer than a typical description but earns its length by covering multiple aspects. Slight verbosity in listing example queries could be trimmed, but overall it's effective.

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 there is no output schema, the description fully explains the return format: category-bucketed example questions with the exact tool and argument shape. It also covers invocation modes, the data source (live catalog), and situational guidance. Nothing critical is missing for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% (the single optional 'topic' parameter is described with an explicit list of allowed values). The description adds meaning by explaining that omitting the parameter gives a cross-category spread, and provides extra examples ('finance', 'pharma', 'betting') that reinforce the schema's enum-ish list. This enriches the schema without redundancy.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for agents that want to know what Pipeworx can do. It specifies the verb ('Returns category-bucketed example questions') and the resource ('drawn from the live catalog of thousands of tools'). It also distinguishes from sibling tools by positioning itself as the FIRST tool to use when unfamiliar with Pipeworx, differentiating from discover_tools and 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?

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to vary the call (no args vs topic) and gives example topics. Although it doesn't state when NOT to use it, the clear directive to use it first establishes precedence 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?

Adds behavioral details beyond annotations: ownership enforcement and soft-delete behavior ('deactivated not deleted') and historical availability via recent_alerts. Annotations already indicate non-destructive and idempotent.

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 action, no redundancy. Every word earns its place.

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

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

For a simple single-parameter tool with good annotations, the description covers the operation's effect and constraints adequately. Output schema absent, so no need to explain return values.

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 covers the 'id' parameter fully (uuid returned by subscribe). Description adds no new parameter semantics beyond 'by id'.

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

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

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

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

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

Clear context on ownership constraint and the deactivation behavior, but no explicit mention of when to use vs alternatives. No exclusions or alternative tool recommendations.

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, and the description adds significant context: the dual pipeline behavior, the precise verdict taxonomy, and the critical caveat that could_not_verify means the check did not happen and must not be shown as evidence. This is rich behavioral disclosure that goes beyond the annotations and contains no contradictions.

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

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

The description is somewhat long but every section carries critical information: usage triggers, pipeline routing, verdict meanings, and the could_not_verify caveat. It is front-loaded with natural-language examples and grows appropriately detailed, though the list of query phrasings 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 compensates by explicitly stating the verdict set, the actual value with citation, and reasoning, plus error semantics. It also covers the routing logic for different claim types and the effect of tolerance_pct, making it self-contained for the agent.

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

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

Schema coverage is 100% with detailed descriptions for both parameters, so the baseline is 3. The description references tolerance_pct and percent-delta math but adds little beyond the schema; it mainly reinforces the schema's own explanation.

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 list of natural-language query phrasings and states 'natural-language claim verification against authoritative sources', which clearly identifies the tool's function. It explicitly distinguishes between company-financial claims and other claims, and names the verdict output, differentiating it from sibling research tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and contrasts the SEC EDGAR fast path with the grounded pipeline. It also warns about the meaning of could_not_verify and unsupported, clarifying when the tool cannot be relied upon, though it does not name sibling tools as alternatives.

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