Arcgis Chatham

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by detailing the default model, the optional Anthropic key behavior, and the per-model return structure, while also disclosing cost implications (BYO key) without contradicting annotations.

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

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

Three sentences, front-loaded with the core function, then key configuration, then use cases. Every sentence earns its place with no repetition of structured data.

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

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

For a tool with one required parameter and full schema coverage, the description covers essential behavior, return shape, and use cases. The annotations handle safety, so nothing critical is missing.

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

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

With 100% schema description coverage, the schema already documents all parameters. The description further clarifies how 'models' and '_apiKey' interact, and notes the default free model, adding practical 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 ('probe') and resource ('LLMs'), clearly stating the tool scores visibility 0-100 per model. However, it does not explicitly contrast with sibling tools like scan_competitor_ai_presence, which could appear similar.

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?

Lists concrete use cases—AI-marketing audits, pre-launch brand checks, competitive monitoring—which provide clear context for when to use it. Does not specify when not to use it or name alternative tools, so it earns a 4 rather than 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds valuable context: routes to 5,462 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and one fast call. 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 somewhat long (~150 words) but well-structured and front-loaded with the key preference over web search. Each sentence adds value: purpose, examples, comparisons, and tier/performance info. Slightly verbose but justified given the tool's default-entry-point role.

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 explains the return format (structured answer with citations). It covers use cases, exclusions (when to use grounded/deep_research), domain coverage, and accounts for aliases. Complete for a question-answering tool with six alias parameters.

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 all six parameters; they are all aliases for 'question'. The description provides examples of questions but does not add semantic detail beyond the schema's alias explanation. Baseline 3 is appropriate since schema covers everything.

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 explicitly states the tool answers factual questions about real-world data by routing to thousands of sources, with specific examples (SEC filings, FDA data, stocks, etc.). It clearly distinguishes itself from siblings by positioning as the default entry point and directing users to ask_pipeworx_grounded and deep_research for specific alternatives.

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 strong usage guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', 'find', 'get the latest'), provides concrete examples, and explicitly says 'START HERE' for most questions. It also states when to step up to alternatives (hallucination-resistant answers → ask_pipeworx_grounded; broad/multi-part → deep_research).

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 this router is experimental, that candidate routing improvements are enabled live when under test, that no candidate is currently active (retired 2026-07-26), and that it currently matches ask_pipeworx exactly. It also clarifies that it is a full working router with no fallback, adding significant behavioral context beyond the annotations.

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

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

The description is well-structured and front-loaded with the key point (beta version of ask_pipeworx). It is slightly verbose with a long first sentence, but every clause provides needed context about live experiments, current state, and usage. It is appropriately sized for a beta tool requiring caveats.

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 complexity of a universal router with 5,462 tools and no output schema, the description covers the relationship to the stable version, current active state, and expected behavior (same response shape). It could mention potential error handling or how to identify active candidates, but it is sufficiently complete for an agent to understand and invoke the tool.

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

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

Schema description coverage is 100% with all parameters documented as aliases for 'question'. The description adds no additional parameter semantics, only stating 'same arguments' as ask_pipeworx. Baseline of 3 is appropriate since the schema already fully describes the parameters.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx with the same universal routing function, and differentiates it from the stable sibling by emphasizing experimental routing improvements and live candidate testing. It states a specific action ('ask', 'route') and scope (5,462 tools, same arguments and response shape).

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, giving clear context. It does not explicitly say 'use ask_pipeworx when you want stable routing', but the beta/stable distinction is implied. It names the sibling ask_pipeworx and contrasts their purposes, though it does not mention other alternatives like ask_pipeworx_grounded.

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 readOnly/idempotent annotations, the description reveals key behaviors: it uses ONLY tool result content, returns structured refusal reasons when data doesn't answer, and costs one extra LLM call. No contradiction with annotations; instead, it enriches the annotation 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 sentences, each earning its place: purpose, mechanism, and usage guidance. Front-loaded with the key differentiator and packed with actionable details 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?

No output schema exists, so the description fully explains return values on success and failure, including refusal reason enums. It also covers cost, usage context, and alternative tools, leaving no critical gaps.

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

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

Schema coverage is 100% for all 6 parameters (all documented as question aliases). The description doesn't add parameter-specific details, but the schema already fully explains them, 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 is a 'hallucination-resistant answer mode' with a specific mechanism (routing, fetching, extracting from tool result only). It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and structured output with evidence, making the purpose unmistakable.

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

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

Explicitly specifies when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups.' Also notes the extra LLM call cost, providing clear alternative 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 the read-only annotations, the description discloses fan-out behavior, response shapes, resolver confidence levels, fallback mechanisms for news sources, safety short-circuits for low-confidence matches, closed-market handling, wide-spread illiquidity flags, and resolution-rule risk parsing. It even advises caution ('ALWAYS inspect these before trusting the analysis block') and warns about recurring void-settlement losses, going far beyond annotation basics.

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

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

The description is lengthy but well-structured with clear section markers (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded purpose. Every sentence contributes meaningful detail, but the density and length prevent a perfect score for conciseness.

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

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

With no output schema, the description fully explains return values: result.market, result.analysis, result.evidence, resolver match fields, parent event data, news fallback indicators, and safety statuses. It also covers edge cases like closed markets, wide spreads, and resolution-rule risks, making it comprehensive for the tool's complexity.

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

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

The schema already covers all parameters with descriptions (100% coverage), but the tool description adds extra context: it explains that include_raw=false keeps responses under 20KB while true yields 50-500KB payloads, and provides fan-out examples mapping market types to data sources, which clarifies the depth parameter's behavior. This goes beyond 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 opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' which uses a specific verb and resource. It clearly distinguishes itself by covering market resolution, classification, fan-out, and market-vs-model comparison, and even lists example use cases like 'should I bet on X' and 'is there edge in Z'.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'). It provides rich context on resolver confidence and safety short-circuits but does not explicitly name alternative tools or exclusion scenarios, though the sibling context implies distinct niches.

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, idempotentHint, destructiveHint), the description discloses significant behavioral traits: pulls latest 10-K revenue/net income/cash/debt, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with citation URIs, and replaces 8–15 sequential lookups. No contradictions with annotations.

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

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

The description is dense but well-structured: trigger phrases, primary purpose, usage preference, type-specific data details, and output behavior. Every sentence adds valuable information without redundancy or fluff.

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

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

Given the tool's moderate complexity and absence of an output schema, the description fully covers what the tool returns (paired data, sorted results, citation URIs), handles edge cases (off-calendar fiscal years), and explicitly justifies its efficiency. This is complete for an agent to select 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 schema coverage is 100%, the description substantially enriches parameter semantics by explaining what 'type=company' pulls (10-K financials) vs 'type=drug' (FAERS counts, FDA approvals, trial counts), and clarifies values are tickers/CIKs or drug names. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with a specific verb ('compare') and resource scope. It also distinguishes itself from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Explicit usage triggers are listed ('Compare X and Y', 'X vs Y', 'which is bigger/better/larger/more profitable', 'rank these companies', 'head to head'), and it explicitly says when to prefer this tool over alternatives. It also differentiates use cases for type='company' vs type='drug'.

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 as read-only, open-world, idempotent, but the description adds substantial behavioral context: account tier restrictions, parallel decomposition across 5,462 tools, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] behavior, contradictions[], excerpting strategy, and expected latency. 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 packed with essential details; every sentence conveys actionable information. Minor redundancy exists ('structured data' / 'not open-web search' repeated) but overall it is well-structured and front-loaded with the account requirement.

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

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

Despite no output schema, the description fully explains the return packet, citations, gaps, contradictions, and timing. Combined with rich annotations and complete parameter schema, it provides all necessary context 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 covers both parameters with descriptions, and the description further enriches depth semantics by detailing 'quick/standard/thorough' hop behaviors, gap recovery, contradictions, and paid plan requirement. It also clarifies question decomposition for broad natural-language queries. Slight redundancy with schema but adds genuine 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?

Description clearly identifies the tool as grounded multi-source research across Pipeworx's structured data sources in one call, with a specific verb ('research') and resource. It explicitly differentiates from ask_pipeworx and notes it is NOT open-web search, distinguishing it from siblings.

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 structured-data questions, and advises ask_pipeworx for single lookups and breaking/current news. Also includes a clear prerequisite (account required, free tier limitation) and fallback instruction for non-signed-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?

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes they are 'ready to call directly, no second schema lookup needed.' This goes beyond annotation data and clarifies the output/return 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 three sentences, front-loaded with the core purpose. The middle sentence lists many domains, which is long but serves as useful scope enumeration. Overall it is efficient and structured, though the domain list adds length compared to more minimal descriptions.

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 adequately covers purpose, usage context, and return behavior (tools with schemas/examples, directly callable). It also provides the key strategic guidance to call this tool first. The combination of annotations and high schema coverage leaves no significant gaps.

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

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

Schema description coverage is 100%, and the schema thoroughly documents the 'query' parameter and its aliases (q, task, search, description) plus 'limit'. The description does not add parameter-specific meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly enumerates the domains it covers (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings as the meta-discovery tool, reinforced by 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

It provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and a clear when-not: 'Call this FIRST... not just one answer.' However, it does not name specific alternative tools to use instead, relying on implicit sibling differentiation, so it misses explicit alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds rich behavioral context: fans out across multiple sources, soft-fails for patents until May 2025, uses a GDELT→GNews fallback, and returns items like recent_filings with specific URIs and sorted fundamentals. 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 information-dense, with example queries front-loaded and output details organized clearly. It earns its length by covering multiple data sources and constraints, though it could be trimmed without losing essential info.

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 takes full responsibility for explaining return values. It enumerates all major components (cik, recent_filings with URIs, fundamentals with sorted period_end, patents, news, LEI) and includes limitations (patents soft-fail, names not supported), giving a complete picture for a complex multi-source 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 already covers both params (type enum and value description) with 100% coverage. The description adds concrete examples ("AAPL", "0000320193") and emphasizes zero-padding, reinforcing the schema but not significantly extending meaning. Slightly above baseline due to these concrete format hints.

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

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

The description clearly states the tool's function—building a full cross-source profile of a US public company—supported by concrete example queries ("Tell me about X", "research Acme", etc.) and a detailed list of returned data. It distinguishes itself from sibling tools by emphasizing a single parallel call instead of chaining single-pack lookups.

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

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

Provides explicit guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also names an alternative (resolve_entity) when the user only has a company name, clarifying when not 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 mark destructiveHint and idempotentHint, so the bar is lower. The description adds context that it only affects 'previously stored memory' and mentions 'sensitive data the agent saved earlier', giving insight beyond just 'delete'. It doesn't disclose irreversibility beyond destructiveHint, but that's already captured.

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

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

The description is three short sentences that front-load the core purpose ('Delete a previously stored memory by key') and then efficiently cover when to use it and how it relates to siblings. No unnecessary content.

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

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

For a simple tool with one parameter, no output schema, and annotations covering destructive and idempotent behavior, the description fully explains the tool's purpose, usage context, and relationships to related tools. It is complete for its complexity.

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

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

The schema fully documents the single 'key' parameter with 'Memory key to delete', and the description merely repeats 'by key' without adding extra meaning. With 100% schema coverage, the description doesn't need to compensate.

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

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

The description clearly states the action ('Delete') and resource ('previously stored memory by key'), making it instantly obvious what the tool does. It also distinguishes from sibling tools like remember and recall by focusing on deletion.

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

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

Provides explicit usage scenarios ('context is stale, task is done, or you want to clear sensitive data') and names complementary tools (remember and recall), which helps the agent decide when to use it. Even though it doesn't explicitly say 'when not to use', the positive guidance is strong and the alternatives are implied.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable process context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and clarifies the output is 'a single text blob ready to drop at site-root/llms.txt'. This goes beyond annotations without contradicting them.

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

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

Three focused sentences: purpose, process/output, and use cases. No redundant phrasing; the description is front-loaded with the verb and resource, and every sentence earns its place.

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

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

For a simple two-parameter tool without an output schema, the description fully covers what it does, how it works, what it returns, and when to use it. It mentions the output format and destination, compensating for the missing 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 input schema already fully describes both parameters (url and max_links) with 100% coverage. The description adds no additional parameter-specific semantics, so the baseline of 3 is correct.

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 'Generate' and resource 'production-ready llms.txt file for any URL', clearly distinguishing this from sibling tools like scan_competitor_ai_presence by emphasizing the file output. It also names target crawlers and the output format, making its function unmistakable.

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

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

Provides clear use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') without naming specific alternatives or exclusions. This is strong context but stops short of explicitly saying when not to use it.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by specifying exactly what schema details are returned (fields with types, geometry, count, capabilities). This clarifies expected output without contradicting annotations, and no additional side effects are disclosed, which is acceptable given 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?

Single sentence that is front-loaded with the action and resource, enumerates outputs without redundancy. 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?

For a one-parameter tool with no output schema, the description adequately outlines the return contents. It could mention potential errors or URL format specifics, but the schema covers the example. The annotations cover safety, so the description is sufficient for a simple task.

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 only parameter, url, is fully described in the schema with an example. The description merely repeats 'by url' and does not add new constraints or format details beyond the schema. Since schema coverage is 100%, 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?

Description uses specific verb 'Get' and clearly identifies the resource: an ArcGIS Feature/Map Service layer's schema. It enumerates the returned components (fields, geometry type, record count, capabilities), distinguishing it from sibling query_layer which would fetch data rather than 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?

Description states the tool retrieves schema information by URL, implying its use when metadata about a layer is needed. It does not explicitly mention alternatives or exclusions, but the specificity of the output makes its use case evident. Since no when-not-to-use is provided, it scores a 4 rather than 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 convey read-only, idempotent, non-destructive behavior. The description adds that it returns the caller's own subscriptions (scope) and the specific list of fields, which gives useful context beyond the annotations, but it doesn't discuss pagination or other behaviors. With annotations covering safety, this is adequate but not rich.

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

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

Two concise sentences—purpose, return fields, and usage guidance. No filler words. Very 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?

Given the simple schema and rich annotations, the description fully covers what the agent needs: what it returns, scope, and when to use. The lack of an output schema is compensated by listing fields. Highly complete.

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

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

The schema covers 100% of the single parameter with a clear description for include_inactive. The tool description doesn't add anything 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 uses the verb 'List' with a specific resource 'the caller's active subscriptions' and enumerates the fields returned. This clearly distinguishes it from sibling subscription tools like subscribe 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?

It explicitly advises when to use: to review what you're monitoring before adding more or to find an id to cancel. However, it doesn't mention alternatives or exclusions, so it's clear context but not exhaustive.

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 the claim_token flow (returns token when filing without account, later pass it back to read status), daily team digest reading, rate limit of 5 per identifier per day, and that it's free. Annotations are all false (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the full burden and exceeds it with concrete operational detail.

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

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

Front-loaded with purpose, then usage, exclusions, token mechanics, and limits. Every sentence earns its place—there is no redundancy. Despite being longer than typical descriptions, the density of critical operational information justifies the length.

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

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

Even though there is no output schema, the description tells exactly what filing returns (a claim_token) and how to later check resolution status. It also covers rate limiting, scope (only Pipeworx connection tools), and guidance on what to write. Complete for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra context: explains the claim_token round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and gives message content guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches the parameter semantics beyond the schema.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes itself from sibling research/query tools by being the dedicated feedback channel for Pipeworx tools, covering bug reports, feature requests, data gaps, and praise.

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

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

Provides explicit when-to-use scenarios: bug (wrong/stale data), feature/data_gap (wished tool absent), praise (surprisingly good). It also explicitly excludes non-Pipeworx MCP servers: 'if the tool came from a different MCP server... file it with that server instead,' and clarifies what content to include ('don't paste the end-user's prompt').

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: caching behavior (5min-1h depending on window), self-aggregating nature, derivation from CF analytics-engine, no PII, and output granularity (pack, tool, count). 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 moderately sized but well-structured: front-loaded with the core purpose, followed by use cases, then provenance and caching details. Each sentence contributes new information; there is no redundant filler. Slightly longer than the ideal two-sentence version, but every detail 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?

Even without an output schema, the description explicitly states return contents (top tools, top packs, total call volume) and output structure (pack, tool, count). Combined with comprehensive annotations, this is complete for a simple read-only aggregation tool. It covers what the agent needs to know for selection and invocation.

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

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

The schema covers 100% of the lone 'window' parameter, including enum values, default, and trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description does not need to add parameter syntax or semantics; the only extra is that caching varies by window, which is behavioral rather than parameter meaning.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume' over a recent window. The verb 'returns' is specific, and the resource (aggregated Pipeworx usage) is unambiguously identified. It distinguishes itself from sibling tools like discover_tools by focusing on aggregate popularity rather than individual tool discovery.

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

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

The description provides three explicit 'Useful for' scenarios: discovering hot data sources for current events, confirming a canonical tool choice, and checking alignment with collective agent behavior. It does not explicitly name alternatives or state when NOT to use it, but the context is clear enough for an agent to decide between this and other discovery tools.

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

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

Discloses detailed behavioral traits beyond annotations: fill check against live CLOB depth, threshold of >3pp for deviations, Jaccard similarity ≥0.30, placeholder filtering, and the condition 'realizable_edge_pp ≤ 0 means ... do not trade it'. This adds substantial context while readOnlyHint/idempotentHint already signal safe read-only behavior. No contradiction with annotations.

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

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

The description is dense and front-loaded with the main purpose, but length is justified by the tool's complexity (three modes, sophisticated filters, output details). Internal section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) help navigation. Slightly verbose, but every sentence carries functional value.

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

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

With no output schema, the description fully specifies the response structure: opportunities[] fields, partition_check object in event mode, and fill check outputs including thin_legs[]. It also covers edge cases (placeholder slugs, low similarity) and provides alternative tool references, making it complete for a complex tool.

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

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

Even though schema coverage is 100%, the description enriches both parameters: for event it explains slug formats, accepted URLs, and that it walks child markets; for topic it defines a seed question with examples and explains cross-event scanning. It also covers the no-args mode, adding meaning 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?

Description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific resource (Polymarket) and the mechanism, and distinguishes among three modes (trending_scan, event, topic). It also differentiates from the sibling tool polymarket_fill_risk by pointing users there for sizing.

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

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

Provides explicit guidance for when to use each mode: no-args for trending_scan, event mode 'recommended for a specific market', and topic mode 'for cross-event scanning'. It also contrasts single-event vs cross-event capabilities and explicitly directs to polymarket_fill_risk for custom sizing, and warns not to trade when fill check shows no realizable edge.

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 the tool as read-only, idempotent, and non-destructive, so the bar for additional value is high. The description adds extensive behavioral context: the 1-hour KV cache, the three-segment response structure, the 24h-move warning, the tradeable-edge knobs, and the diagnostic counters that explain why segments are empty. This goes far beyond what annotations convey.

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

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

The description is long but exceptionally well-structured: it uses section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the purpose. Every sentence carries necessary information—model formulas, gate conditions, response keys, and caveats—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?

Despite lacking an output schema, the description fully documents the response structure (by_segment, fed_candidates, _diagnostics) and explains what each segment contains, why fed bets are excluded from ranking, and how each knob affects results. It even explains why segments can be empty. Given the tool's complexity, this is complete enough for an agent to select and invoke it correctly without extra 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?

With 100% schema description coverage, baseline is 3, but the description adds substantial meaning beyond the schema. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly inside top_legs because partition arbs return kelly_fraction_half=0 at the parent level, and it justifies slippage_pp with Polymarket's fee structure and typical spread. This deepens an agent's understanding of how parameters interact.

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 also clearly differentiates from sibling tools by describing its three model families and explicit discovery use case, so an agent can distinguish it from polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description states its intended use context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear guidance on when to use it, but it does not explicitly mention alternative tools or exclusions, so it stops short of a 5.

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

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

Discloses multiple behavioral traits beyond annotations: snapshot TTL limits, cache-miss snapshot gaps, daily-close decay measurement, and signed edge values (negative = SELL YES). These add important interpretive context and data freshness caveats.

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?

Description is front-loaded with purpose, then args, then detailed RESPONSE breakdown, then LIMITS. Every sentence adds informative detail; organized with clear labels and dense but not redundant.

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

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

No output schema, so description fully compensates by detailing tracked[], expired[], and snapshot_dates[] fields, plus limitations (TTL, gaps, decay derivation). Covers edge cases and data interpretation thoroughly.

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

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

Schema coverage is 100% with descriptions for both days and window. The description adds 'snapshot family' terminology for window but otherwise restates schema info, so it adds marginal value beyond the schema.

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

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

Description states a specific purpose: edge persistence and decay telemetry from daily snapshots, answering how long edges exist and whether they're shrinking. This distinguishes it from sibling tools like polymarket_edges (current edges).

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 on when to use: to assess edge durability and decay, with an example of fresh vs. old edges. Does not explicitly name alternatives or exclusions, but the usage scenario is well-defined.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds substantial behavioral detail: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), identifies thin legs, and warns about forced_directional_risk. It also explains the real-world loss mode (partial basket fills converting arbitrage into an unhedged directional position), which goes well beyond the annotations. No contradiction.

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

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

The description is quite long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loads the core purpose. Every sentence contributes useful information, though the length is substantial. It earns a 4 for organized density rather than a 5 for brevity.

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 dual-mode tool with no output schema, the description thoroughly enumerates expected return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg fill detail, thin_legs[], etc.) and explains the behavioral context (thin books, partial fills). An agent can confidently decide when and how to invoke it and what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the dual-mode interpretation of parameters: 'size_usd' means spend/proceeds in single-market mode but settlement notional (shares per leg) in basket mode, and 'side' has an auto default in basket mode. This goes beyond the schema's per-parameter descriptions, earning 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 a clear, specific statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes this tool from siblings by naming when it should be used ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'). The dual-mode structure (single-market vs basket) is clearly defined.

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

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

Explicit usage guidance is given: use before acting on polymarket_arbitrage sell/buy-every-leg signals or polymarket_edges trades above ~$500. It explains the core rationale (theoretical overround on thin books is not capturable, partial fills cause unhedged directional exposure). This provides clear context for when to use this tool versus alternatives.

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

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

The description goes far beyond the readOnly/idempotent/openWorld annotations by detailing failure modes, compatibility_warning conditions, temporal_alignment semantics, and skipped-cross counters. It clearly explains what the tool does when bet shapes are non-equivalent and when events are semantically unrelated, providing rich behavioral context that annotations alone 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 long but well-structured: purpose first, then modes, response, and safety fields. Every sentence contributes useful information for a complex tool, though some redundancy exists (e.g., repeated emphasis on pre-mapped ≠ tradeable). It is appropriately sized for the tool's complexity, but not minimal.

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 thoroughly explains the response format: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped_cross counters. It also explains edge cases and failure conditions, making the tool's behavior fully understandable without additional schema information.

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 already describes all three parameters, the description adds crucial semantics: topic mode auto-fetches matching events, explicit ticker/slug override the mapped sides, and topic values are listed explicitly. This explains the interaction between parameters and the two operational modes, adding meaning beyond the raw 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 immediately identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools. It specifies two operational modes (topic shortcuts and explicit ticker/slug pairings) and what the response contains, making the purpose concrete and actionable.

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

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

The description gives clear context on when to use each mode: use topic shortcuts for pre-mapped macro events or explicit ticker/slug for custom pairings. It also warns that pre-mapped topics are often not tradeable and explains compatibility warnings, but it does not explicitly name alternative sibling tools or state when not to use this tool versus those alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds behavioral detail beyond annotations: it states the return type ('attribute rows (and geometry)') and describes the query parameters (SQL-like where, out_fields, order_by, limit, offset). This adds meaningful 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 three short sentences, with the core purpose front-loaded. Each sentence contributes: first defines what the tool does, second lists the key parameters, third provides a usage hint. No filler or redundant 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?

The description covers the tool's purpose, all six parameters (url, where, out_fields, order_by, limit, offset), the return type, and even a sampling strategy. Since there is no output schema, it doesn't need to detail return structure further. It omits edge cases like error behavior or pagination limits, but for a query tool with this complexity, the description is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic value by explaining that the query is SQL-like, by demonstrating the sample pattern (where="1=1" + out_fields="*"), and by tying the url parameter to the output of search_datasets. This goes beyond replicating 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 states a specific verb ('Query') and a clear resource ('an ArcGIS Feature Service / Map Service layer by its url'), distinguishing it from siblings like search_datasets (which finds datasets) and layer_info (which describes a layer). It further clarifies the tool's scope by listing the SQL-like parameters and specifying that it returns attribute rows and geometry.

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 ties the URL to search_datasets ('by its url (from search_datasets)'), indicating the preferred upstream workflow. It also provides a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). While it doesn't name alternative tools to avoid, the context makes the intended use 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 destructiveHint=false, and the description adds context: scoping to identifier (anonymous IP, BYO key hash, account ID) and behavior of omitting the key to list all keys. 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?

Two sentences efficiently convey purpose, usage, scoping, and relationships to siblings without wasted words. Front-loaded with the core action.

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

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

The tool is simple (one optional parameter, no output schema), and the description fully covers behavior, scoping, and pairing with related tools. No gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100% with the key parameter already described. The description adds practical examples of what values keys may hold ('user's target ticker, an address, prior research notes') and clarifies the omit-to-list behavior, 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?

Description clearly states it retrieves a value saved via remember, or lists all keys when the key argument is omitted. This is a specific verb+resource definition that distinguishes it from the sibling tools remember and forget.

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

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

Explicit guidance on when to use: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). Also names alternatives: 'Pair with remember to save, forget to delete.'

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 setting mark_read:true flags returned events as read, which is a state-modifying behavior. This directly contradicts the annotations readOnlyHint: true and idempotentHint: true, which assert no side effects and idempotency. This is an annotation contradiction.

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

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

The description is two sentences and front-loaded. The first sentence establishes the action and output; the second covers filtering, mark_read behavior, and alternative access. Every sentence adds 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 is highly complete: it describes the return fields (source, citation_uri, raw event payload), the filtering options, the mark_read side effect, polling suitability, and an alternative access URL. The remaining parameters (limit, unread_only) are covered by the schema, so the description does not need to repeat them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it provides an example for the type filter (e.g. 'sec_8k'), explains the since parameter as an ISO timestamp, and details the semantic effect of mark_read (flagging events read so the next call only shows newer ones). This goes beyond what the schema already documents.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed', using a specific verb and resource. It distinguishes itself from sibling tools like list_subscriptions (which lists subscriptions) by focusing on the alert events feed.

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

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

The description provides clear usage context by stating 'Polls work fine' and mentions an alternative access method via GET registry.pipeworx.io/alerts.json for scripts and dashboards. It implies the tool is suitable for reading recent alerts, but does not explicitly call out when not to use it relative to sibling tools.

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

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

Beyond the read-only/idempotent annotations, the description discloses concrete behavioral traits: fan-out to SEC EDGAR, a GDELT→GNews fallback triggered by rate limits or 5xx, and a soft-fail for USPTO patents due to the PatentsView API sunset. It also explains the return structure (changes[] grouped by source, total_changes, citation URIs), which is valuable context not present in structured annotations.

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

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

The description is long but information-dense and logically ordered: intent examples, then data-source mechanics, then parameter format, then return shape, then alternative guidance. Every sentence carries value, though a few query examples could be trimmed without loss. It is not padded or repetitive.

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

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

Given no output schema, the description sufficiently covers the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and major behaviors (API fan-out, fallbacks, patent soft-fail). It could further detail the fields inside each change item or pagination, but for a tool of this complexity it is largely complete.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful usage detail by enumerating accepted `since` formats (ISO date vs relative shorthand like '7d', '30d', '3m', '1y') and suggesting '30d' or '1m' for typical monitoring. It also clarifies that `value` can be a ticker or CIK, reinforcing the schema's intent rather than merely repeating it.

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

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

The description opens with concrete user-intent examples and explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It goes beyond a vague statement by naming the underlying data sources (SEC, GDELT/GNews, USPTO) and contrasts with entity_profile, making the purpose unmistakable.

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

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

It explicitly directs users to 'use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window,' providing a clear alternative. The description also implies this tool is for time-bounded change monitoring, covering the primary usage context effectively.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful context by explaining scoping by agent identifier, persistent vs. 24-hour memory based on auth status, and the key-value storage format—details not available in annotations alone.

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

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

The description is four sentences, front-loaded with the primary action, then usage guidance, storage details, and companion tools. Every sentence adds distinct information with no redundancy, achieving high information density.

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 simple 2-parameter save tool with no output schema. The description covers purpose, usage context, persistence behavior, and related tools. It does not mention return value or overwrite behavior, but these are minor for a save operation. Annotations fill in the safety profile, making the overall package sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that storage is 'scoped by your identifier', which clarifies the namespace behavior beyond what the schema says. It also reinforces that value accepts any text, but the scoping detail pushes it above 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 saves data for later reuse, using the verb 'Save' and specifying the resource (key-value memory). It distinguishes itself from sibling tools by explicitly mentioning recall and forget, making it clear this is the storage operation.

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

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

It provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference) and explains the persistence difference for authenticated vs. anonymous sessions. It also names companion tools recall and forget, giving clear context for when to use this tool versus alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: cascading through multiple endpoints, auto-disambiguation, return fields (ticker, CIK, RxCUI, etc.), and citation URIs. This gives the agent a clear picture of what happens internally and what output to expect, going well beyond the safety hints.

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

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

The description is efficiently structured: leading example queries, a crisp purpose statement, a clear directive, and then a breakdown by supported type. Every sentence adds value—no filler or repetition. The length is justified by the rich information about return formats and citation URIs.

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 fully covers return values for both entity types, including the canonical identifier, additional fields, and citation URIs. It also covers disambiguation behavior and the fact that it aggregates multiple lookups. It is completely self-contained for the agent to invoke 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%, but the description adds significant extra meaning. It explains what each type returns, provides concrete examples (AAPL, 0000320193, ozempic, metformin), clarifies that company accepts ticker/CIK/name, and notes auto-disambiguation. This goes far beyond the bare schema descriptions, enriching the semantics for both parameters.

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

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

The description clearly states the purpose: resolving a user-spoken name to a canonical/official identifier needed by other tools. It gives specific verbs ('resolve', 'look up', 'find') and resource types ('company', 'drug'), and distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID resolution rather than profiling or comparison.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing a strong when-to-use directive. It also states that it replaces 2-3 manual lookups, implying efficiency. However, it does not provide when-not-to-use guidance or name alternative tools, so it falls short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that it probes each entity via ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds valuable behavioral context about the internal process and output 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?

The description is four sentences, front-loaded with the main purpose, followed by mechanism, use case, and return format. Every sentence serves a purpose with no redundancy or fluff.

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

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

Given the tool's complexity (multi-entity, sub-call to ai_visibility_check, optional API key) and the absence of an output schema, the description adequately covers the return format and internal behavior. Schema and annotations fill the remaining gaps, making it complete enough for an agent to select 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?

Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter details beyond what the schema already provides, but it does reinforce the concept of 'your brand + N competitors' and 'first entry as subject', which is already in the schema. No additional compensation needed.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, distinct from the single-entity ai_visibility_check and generic compare_entities sibling. It specifies the action (probe, rank, surface) and the resource (entities' AI visibility).

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

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

The description provides clear context for when to use it (competitive AI-marketing audits) and gives a concrete example query. It does not explicitly name alternatives or state when not to use it, but the context strongly implies usage for multi-entity comparison.

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 annotations declare read-only and idempotent, but the description adds substantial behavioral context: it fans out to multiple services, degrades gracefully on partial failures, and notes that bundlephobia's first measurement can take 5-30s and may result in sources_failed. This goes well 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 information-dense and front-loaded with the core purpose. It is slightly longer than minimal, but every sentence covers a distinct aspect: purpose, usage, return fields, ecosystem scope, and failure behavior. The structure is logical and efficient.

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

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

With no output schema, the description compensates by listing the summary block fields, per-advisory detail, links, and alternative versions. It also covers ecosystem limitations and partial failure behavior. This is complete for a composite external-data tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly add meaning beyond the schema; it only reinforces that 'version' defaults to latest and that only npm packages are accepted. No additional parameter details are provided.

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: a composite check for npm packages, combining deps.dev and bundlephobia. It uses a specific verb ('scan' implied) and resource, and differentiates itself by explicitly limiting to the NPM ecosystem and listing the exact return fields.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an alternative for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations declare read-only, idempotent, and non-destructive behavior, and the description adds value beyond them by detailing the exact return fields (name, summary, record_count, owner/org, Feature Service url). It does not contradict annotations and provides useful follow-up 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?

Two sentences, front-loaded with the core action and resource, and every word earns its place. It efficiently conveys purpose, return values, and a nested tool relationship without padding.

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, the schema fully documents all three parameters, and the description enumerates the return fields and the next-step tools. There is no missing obvious information; the description is complete for its intended discovery use case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter semantics beyond the schema; it merely echoes 'by keyword' for the query parameter and does not mention limit or org_id explicitly.

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

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

The description clearly states a specific verb ('Search') and resource ('Chatham County GIS open geospatial datasets') with keyword-based scope. It also lists the return fields, distinguishing it from sibling tools like query_layer and layer_info by mentioning the url handoff.

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 guides usage by stating 'pass that url to query_layer / layer_info', indicating when to use this discovery tool versus the data-retrieval tools. It also implies the search is a prerequisite to further queries, giving clear context without exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description adds rich behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. These are non-obvious behaviors that materially affect agent expectations.

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

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

The description is four sentences, front-loaded with the purpose, and every sentence adds substantive value (context, usage, pairing, technical details). It is slightly dense but well-structured, not verbose or padded.

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

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

Despite having no output schema, the description fully covers return format (top-N passages with offsets and similarity scores), usage guidance, pairing with another tool, and technical constraints (embedding model, window size, character cap). No major 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?

Schema coverage is 100%, so the baseline is 3. The description adds context beyond the schema by clarifying that 'text' is 'the text you already pulled' and giving concrete query examples like 'supply-chain risk' and 'fiscal year 2024 revenue'. It also explains the output as top-N passages, which maps to the 'limit' 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 'Semantic search INSIDE a fetched record', which clearly states the verb and resource, and distinguishes it from siblings like ask_pipeworx_grounded or ask_pipeworx. The scope is specific: search inside already-fetched text, not over the whole knowledge base.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt', providing clear context for when to deploy the tool. It also mentions a companion tool 'ask_pipeworx_grounded' and a workflow, but does not explicitly state when not to use this tool or provide a direct alternative for the same goal.

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=false, idempotentHint=true), the description discloses substantial behavioral details: anonymous and BYO accounts cannot persist subscriptions, webhook delivery includes a one-time signing secret, and auto-disabling after 10 consecutive failing runs. These details go well beyond the basic annotation hints and fully inform the agent of consequences and prerequisites.

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

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

The description is long but highly structured: it opens with the core purpose, then prerequisites, then each type with examples, then delivery channels. Every sentence carries useful information, and the format uses clear separators. While not as terse as a two-sentence description, the complexity of the tool (multiple types, multiple channels) justifies the length.

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

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

Given the tool's complexity (nested objects, enums, multiple delivery options) and no output schema, the description fully compensates by stating the return value (subscription id, and webhook secret for webhook) and all constraints (phone verification, 10/day cap, auto-disable). It covers prerequisites, type-specific parameters, and delivery options, making the tool comprehensively self-explanatory.

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

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

Although schema coverage is 100%, the description adds rich semantic value by providing concrete examples for each subscription type (e.g., items:["5.02"] for officer change, {topic:"fed"} for polymarket_edge, {series_id:"UNRATE"} for fred_series). This goes beyond the schema's descriptions and clarifies the exact expected structure and acceptable values.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and explicitly says it 'Returns the new subscription id.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and provides concrete type examples (sec_8k, polymarket_edge, fred_series) that further clarify scope.

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

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

The description provides clear context for when to use the tool: it requires a Pipeworx OAuth account, and mentions the always-on feed channel as an alternative to email/sms/webhook, saying to 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json.' While it doesn't explicitly say 'use recent_alerts instead of this for pulling,' the guidance implies the distinction between creating a long-term subscription and simply fetching current alerts.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds valuable behavioral context: it returns category-bucketed example questions drawn from the live catalog, each with the exact tool+argument shape, and explains the effect of passing a topic. 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 longer than typical but every clause serves a purpose: example queries, return format, parameter guidance, and usage timing. It is slightly dense and could be tightened, but it remains well-structured and front-loaded with the most important onboarding cues.

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 1-parameter, read-only tool with no output schema, the description completely covers purpose, usage, return format, and parameter behavior. It also connects to the broader tool ecosystem by mentioning meta-tools, making it self-sufficient for an agent deciding when and how to invoke it.

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

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

The schema covers the single topic parameter 100%, but the description supplements it with concrete examples ('finance', 'pharma', 'betting') and clarifies the default behavior when omitted ('cross-category spread'). This adds real meaning beyond the schema's basic type/description.

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 role as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It uses a specific verb (suggest) and resource (questions), and distinguishes itself from siblings by naming meta-tools and positioning itself as the first stop.

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

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

Explicit usage guidance is provided: 'Use 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 the two calling modes (no arguments vs. topic) and lists example topics, making when-to-use very clear.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: ownership enforcement, deactivation rather than deletion, and preservation of historical events. This adds significant context that annotations alone do not provide, such as the specific side effect on recent_alerts.

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, no filler, and the most important information (cancel by id) is front-loaded. Every clause adds value, covering ownership and persistence behavior without unnecessary elaboration.

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 mutation with no output schema, the description is thoroughly complete. It explains what happens (deactivation), the ownership restriction, and the impact on historical data, leaving no critical gaps for this complexity level.

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

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

The single parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further semantic detail beyond this, so with 100% schema coverage, 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 clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription), distinguishing it from siblings like subscribe and list_subscriptions. The verb-resource pairing is specific and unambiguous.

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

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

The description gives clear context: ownership is enforced, and it explains the effect on historical events (available via recent_alerts). While it doesn't explicitly name alternatives, the context makes it clear when to use this tool versus others, and the ownership constraint is a practical usage guideline.

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

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

Annotations already convey read-only, idempotent behavior. The description adds meaningful process details: the structured SEC EDGAR + XBRL fast path with 'exact percent-delta math,' fallback to a grounded pipeline, and the return of a verdict, cited value, and reasoning. This goes well beyond the annotation hints.

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

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

Despite being long, the description is tightly packed with useful information, opens with concrete example queries, and flows from use case to routing to output. There is no filler or repetition of schema content, so each 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 enumerating possible verdicts, the actual value with citation, and reasoning. It also explains both processing paths and how tolerance affects grading, making tool behavior predictable 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?

The input schema provides 100% coverage for both parameters, including detailed descriptions of 'claim' with example phrases and 'tolerance_pct' with overrides, defaults, and purpose. The prose description does not add parameter-specific meaning beyond this, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a claim verifier, opens with realistic invocations like 'fact check' and 'verify the claim that...', and specifies the object of verification (natural-language factual claims). It also distinguishes its purpose from generic research by noting it replaces a multi-step pipeline and routes to structured SEC/XBRL versus grounded sources.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further divides use into company-financial claims versus all other factual claims, with automatic routing, giving the agent a clear decision boundary even without naming sibling tools.

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