Arcgis Austin

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable context: default model 'Workers AI Llama-3.3-70b (free)', the BYO key cost implication for Anthropic, and the return format. No contradiction with annotations.

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

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

Three sentences: main purpose, default/key behavior, return format, and use cases. Front-loaded with the core function, every sentence earns its place.

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

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

Despite lacking an output schema, the description specifies the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' Combined with annotations and full parameter docs, the tool is fully specified for correct 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 all four parameters with descriptions. The description enriches parameter semantics by explaining that `_apiKey` is only needed when including 'anthropic' in models and that users pay Anthropic directly, plus the default model behavior.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' This specific verb+resource combination distinguishes it from sibling tools like ask_pipeworx, which focus on asking questions rather than assessing 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 use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly name alternative tools or specify when not to use, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent, and the description adds context about routing to 5,462 verified sources, filling arguments, returning pipeworx:// citation URIs, and being the default entry point on every tier. It doesn't detail rate limits or edge cases but enriches the annotations without contradicting them.

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

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

The description is long but front-loaded with the critical 'PREFER OVER WEB SEARCH' directive and each subsequent sentence adds value: domain list, routing behavior, trigger phrases, examples, escalation paths, and tier notes. It is dense but organized and 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?

Given the tool's complexity (a meta-router over thousands of sources), the description covers use cases, coverage domains, alternative tools, citation output, and default-position guidance. It lacks explicit return-schema details but hints at structured answers with citation URIs, which is acceptable since no output schema is provided.

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

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

Schema coverage is 100%: all six parameters are documented as aliases for 'question' with a clear description. The description adds examples of questions but no parameter-specific syntax beyond that; the baseline 3 applies since the schema carries the full parameter semantics.

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

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

The description clearly states it routes factual questions to 5,462 tools and returns structured answers with stable citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them and describing when each is appropriate.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists trigger phrases plus concrete examples, then says 'Step up only when needed' with named alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context: live candidate testing, current inactive status (matching ask_pipeworx exactly), and that it is a full working router with no fallback. This exceeds what annotations alone 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?

Four sentences, all information-dense: identifies the beta nature, current state, usage, and operational status. No fluff; each sentence earns its place and the key point is front-loaded.

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

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

The description fully explains what the tool is, how to use it, its relationship to ask_pipeworx, and current experimental status. With annotations covering safety, no output schema is needed; the description notes the response shape is identical to ask_pipeworx.

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

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

Schema description coverage is 100%, with all six parameters documented, including aliases. The description mentions 'same arguments' as ask_pipeworx, but adds no new parameter-specific meaning. Baseline of 3 is appropriate since the schema carries the load.

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

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

The description states it is a 'Beta version of ask_pipeworx' and a 'universal router' with the same tools, arguments, and response shape. It clearly differentiates from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing', naming the stable alternative and giving a clear condition. It doesn't explicitly say when not to use it, but the context implies it's for experimental routing comparisons.

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?

Goes far beyond annotations. Details the extraction mechanism (uses ONLY tool result), describes full success and refusal response shapes, lists specific refusal_reason enums, and discloses the extra LLM call cost. No contradiction with readOnlyHint/openWorldHint/idempotentHint 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?

Every sentence adds unique value: definition, comparison with ask_pipeworx, return format, refusal reasons, usage criteria, and cost/alternative guidance. Front-loaded with the key differentiator; no fluff.

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

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

The description compensates for the lack of an output schema by specifying the exact return shape and refusal reasons. Combined with annotations and schema, it fully informs the agent of safety, parameters, behavior, and when to use. No 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% (all six parameters are aliases for 'question' and fully documented in the schema). The description does not add additional parameter-level meaning, so the per-rules baseline of 3 applies. It does mention 'fills arguments' generally, but not specific to individual 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 opening phrase 'Hallucination-resistant answer mode for high-stakes reads' clearly identifies a specific verb (answers with extraction) and resource (Pipeworx data). It distinguishes from siblings by explicitly naming ask_pipeworx and contrasting the grounded extraction behavior. The purpose is unambiguous.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and 'must not invent facts'. Provides alternatives: 'prefer ask_pipeworx for casual lookups' and mentions same routing as ask_pipeworx. Includes cost tradeoff (one extra LLM call) as a decision factor.

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 annotations by disclosing the resolver contract (market_match_confidence, alternatives, suggestions), status codes (low_confidence_match, market_closed_or_inactive), parent-event extractor, news fallback with retry_after_sec, wide-spread warnings, and cancellation-rule risk with ev_impact. It also explains blocking behavior and safety short-circuits. No contradictions with the readOnlyHint/idempotentHint annotations—this is a read-only research tool.

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 it is front-loaded with purpose and usage in the first two sentences, then organized with CAPS labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) for clear scanning. Every section carries decision-relevant info, but the sheer volume and some redundancy (e.g., multiple mentions of closed markets) keep it from a 5.

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

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

With no output schema, the description fully carries the burden of explaining return values and edge cases. It comprehensively describes result.market, result.analysis, result.evidence, the resolver contract, parent_event partition, news fallback fields, status codes for blocking paths, and cancellation-rule risks. This is an extremely complete picture for a tool this complex.

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

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

The input schema already covers all three parameters with descriptions and examples (100% coverage). The description adds contextual examples for the market parameter (slug, URL, question text) and shows fan-out behavior, but it does not add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names a specific verb ('Research'), a specific resource ('Polymarket bet'), and the method ('pulling relevant Pipeworx data'). It also distinguishes itself from siblings by describing its fan-out to category-specific data packs and its evidence+comparison output, which is unique among the listed sibling tools.

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

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

The description provides explicit usage guidance with concrete examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes classifier lists and fan-out examples to make the intended use cases concrete. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools for comparison, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant context: data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This exceeds the baseline and fully discloses behavior.

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

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

The description is dense but well-structured: trigger phrases, preference directive, per-type details, sorting behavior, and return format. Every sentence contributes new information and it's front-loaded with the most actionable content. No filler.

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

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

For a tool with two types, up to 5 entities, and no output schema, the description comprehensively covers what it does, data sources, edge cases, output format, and efficiency benefits. It provides enough detail 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 already covers 100% of parameters with descriptions. The description adds value by providing concrete examples (AAPL, MSFT, ozempic, mounjaro), elaborating on what each type pulls (financials vs. adverse events), and specifying that values are tickers/CIKs or drug names. This is more than a simple repeat of schema info.

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 comparison of 2–5 companies or drugs in one call, using specific verbs like 'compare' and 'rank'. It distinguishes itself from sequential single-pack lookups, making it clear what makes this tool unique.

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

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

Explicitly instructs to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides trigger phrases ('X vs Y', 'which is bigger') that indicate when to use it. Also clarifies differences between company and drug comparisons, giving clear context for selection.

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

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

The description discloses behavior far beyond the readOnly/idempotent annotations: parallel decomposition, gaps[] (never invented), second-hop iterations, contradictions[], citation_uri fetchability, semantic excerpting, latency expectations, and paid plan thresholds. This gives the agent a realistic model of tool 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 long but information-dense; nearly every sentence adds operational value. It is structurally front-loaded with the account warning and core value proposition, though slight repetition about the open-web contrast could be trimmed.

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

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

This tool is complex and has no output schema, so the description carries full responsibility for conveying return values and limitations. It thoroughly covers prerequisites (account), behavior (parallel, gaps, contradictions), output shape (findings packet with citation_uri), and edge cases (current-news returns empty 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?

Although the schema already describes both parameters at 100% coverage, the description enriches the depth parameter with concrete behavioral differences (e.g., 'standard adds a gap-recovery hop', 'thorough adds a full iterative hop'). It also clarifies that the question can be broad or multi-part, aligning with the decomposition model.

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 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' and clarifies it is NOT open-web search. It distinguishes from ask_pipeworx and other siblings, making the unique purpose and scope immediately clear.

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

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

It provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and specifies alternatives for single lookups and current-news topics. It also notes account requirements and points to ask_pipeworx if not signed in, covering both prerequisites and exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the return format and self-containedness beyond annotations.

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

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

The description is well-structured with three sentences covering purpose, usage, and return behavior. The long list of domains is somewhat verbose but each item adds clarity about the tool's coverage. It earns its place as a comprehensive yet efficient description.

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

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

For a discovery tool, the description is complete: it explains what it does, when to use it, what it returns, and how results are structured. No output schema exists, but the description sufficiently covers return expectations. It gives the agent everything needed to decide and invoke.

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 mentions 'describing the data or task' which aligns with the query parameter, but adds no additional parameter-specific meaning. The schema itself provides detailed descriptions and examples for all params.

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

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

The description states a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes from sibling tools like search_datasets or query_layer by focusing on tool discovery rather than data retrieval. The scope is further clarified with examples of domains covered.

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

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

Explicitly provides when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This clearly differentiates from alternatives and gives a tactical recommendation.

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 behavioral context about the parallel fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, and discloses the USPTO PatentsView API sunset and soft-fail behavior. This exceeds what annotations alone 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 dense but efficient; it packs examples, return structure, and caveats into a single paragraph without fluff. It is front-loaded with the purpose and uses semicolons to organize the return fields. Slightly overlong but each clause adds 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?

Given there is no output schema, the description compensates by detailing the return payload (cik, company_name, recent_filings with pipeworx URIs, fundamentals fields, patents, news mentions, LEI). It also covers limitations (names unsupported, USPTO sunset) and the parallel-call behavior, making it fully self-contained.

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

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

Even with 100% schema coverage, the description enriches the `value` parameter with concrete examples ('AAPL' or zero-padded CIK '0000320193') and explicitly states that names are unsupported, pointing to `resolve_entity`. It also clarifies the `type` enum is currently limited to 'company'.

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 queries ('Tell me about X', 'research Acme') and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by advocating over 'chaining single-pack SEC/XBRL/news lookups' for holistic requests.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also provides a direct alternative: if only a name is given, 'use resolve_entity first.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which convey that deletion is permanent and likely safe to repeat. The description adds the nuance of clearing 'sensitive data' but doesn't disclose additional behaviors beyond the annotations. No contradiction found.

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

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

The description is three concise sentences that each serve a distinct purpose: stating the action, providing when-to-use guidance, and mentioning complementary tools. There is 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?

For a simple single-parameter delete tool, the description covers purpose, usage context, and pairing. The absence of an output schema is acceptable given the tool's simplicity, and the annotations handle the destructive behavior, making the description sufficiently complete.

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

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

The schema fully describes the only parameter ('key') with the description 'Memory key to delete', achieving 100% coverage. The description's phrase 'by key' merely repeats this meaning without adding extra semantics, such as allowed formats or examples.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), making the tool's function immediately clear. It also distinguishes itself from sibling tools like remember and recall by explicitly 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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also names complementary tools ('Pair with remember and recall'), offering clear guidance on when to use this tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: it 'fetches the page,' 'extracts title/description/key links,' and emits a single text blob in standard llms.txt format. It also notes it works for 'any URL' and is 'production-ready.' This contextualizes the operation beyond the annotation flags without contradicting them.

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

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

The description is three sentences: first states purpose, second explains mechanics, third lists use cases. Every sentence carries meaningful information with no redundancy or fluff. It is front-loaded with the core function and remains highly scannable.

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 compensates by explicitly stating the output format ('standard llms.txt markdown format' and 'single text blob ready to drop at site-root/llms.txt'). It covers inputs, process, output, and practical use cases. The tool is simple (two params, no nested objects), so this level of detail is 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 input schema has 100% coverage; both 'url' and 'max_links' are described with clear examples and constraints. The description does not add additional parameter semantics beyond what the schema already provides. Since the schema fully covers parameters, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Generate'), a specific resource ('a production-ready llms.txt file'), and the mechanism ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It clearly differentiates the tool from siblings by focusing on llms.txt generation, while siblings like 'scan_competitor_ai_presence' or 'ai_visibility_check' address broader AI visibility concerns.

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

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

The description explicitly lists 'Useful for:' scenarios (indexing a client's site, drafting for a project, auditing a competitor), which clearly communicates when to use the tool. It does not mention exclusions or alternatives, so it stops short of full comparative guidance, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Get' is consistent. The description adds valuable behavioral context by detailing what is returned (schema, geometry type, record count, capabilities), which goes 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 a single, front-loaded sentence that efficiently conveys the tool's purpose and outputs without any unnecessary words or repetition.

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

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

Given the simple one-parameter tool with no output schema, the description adequately covers the return values and leverages annotations for safety. It lacks minor details like error handling or URL format nuances, but these are not critical for this simple read-only tool.

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

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

The input schema has 100% coverage for the single url parameter with a clear description and example. The tool description does not add additional parameter semantics, but with full 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 tool gets an ArcGIS layer's schema, listing specific outputs (fields, geometry type, record count, capabilities). However, it does not explicitly distinguish itself from sibling tools like query_layer, which might query the layer's data.

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?

No guidance is provided on when to use this tool versus alternatives such as query_layer or search_within. There are no exclusions, prerequisites, or context indicating specific use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds context by specifying the return fields and emphasizing 'caller's active subscriptions' (scoping), which is 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?

Two sentences, front-loaded with the core purpose, then a concise usage note. Every word earns its place; no fluff or redundancy.

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

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

For a simple 1-optional-param read tool with no output schema, the description covers purpose, return fields, and usage context completely. It tells the agent exactly what to expect and how to use it.

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

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

Schema description coverage is 100% for the single optional parameter include_inactive, which already explains its meaning. The description does not mention the parameter, but the schema carries the burden, warranting the baseline score of 3.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb ('List') and resource ('subscriptions'). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on read-only listing, and enumerates the returned fields (id, type, params, etc.).

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 to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool relative to subscribing/unsubscribing, effectively naming the alternatives and contexts.

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?

Despite annotations (readOnlyHint=false etc.), the description adds critical behavioral context: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It discloses the claim_token flow and team response cadence ('The team reads digests daily and signal directly affects roadmap'). These go well beyond the binary annotation flags and give the agent a full picture of consequences and limits.

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

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

The description is long but every sentence earns its place. It front-loads the core purpose, then methodically covers when to use, exclusions, token mechanics, rate limits, and roadmap impact. There is no redundant phrasing or filler. The structure is logical, moving from what → when → how → constraints, making it easy for an agent to parse and act on.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' It also covers rate limits, quota impact, and the exclusion of non-Pipeworx tools, making it complete for the agent's decision-making 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?

Input schema covers 100% of parameters with descriptions, providing a baseline of 3. The description adds extra meaning beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' clarifies how to fill message/context, and 'Filing without an account returns a `claim_token`; pass it back later...' explains the claim_token parameter's purpose and usage pattern. This additional guidance 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback types (bug, feature, data_gap, praise) and clearly distinguishes from siblings like ask_pipeworx by stating 'ONLY for tools served by this Pipeworx connection' and contrasting with 'another vendor's Gmail, Splunk, Slack, etc. connector.' This provides excellent differentiation.

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

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

The description gives explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server in your client... file it with that server instead,' naming the alternative action. This is textbook usage guidance with both inclusion and exclusion rules.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds valuable context: no PII, derived from CF analytics-engine, and caching behavior (5min-1h). 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?

The description is well-structured with a clear lead sentence, practical use cases, and data-source context. Every sentence adds value with no repetition or fluff, and it is appropriately sized for a simple tool.

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

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

For a simple read-only tool with no output schema and one optional parameter, the description fully covers purpose, use cases, data composition, and freshness. The information provided is sufficient for an agent to select and 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?

The single parameter 'window' is fully described in the schema at 100% coverage, including the enum and semantics. The description reiterates the window options but adds no new parameter-level information beyond the schema.

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

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

The description clearly states the tool returns trending usage data: top tools, top packs, and total call volume over selected windows. This distinguishes it from sibling tools by focusing on aggregate agent behavior rather than specific data lookup.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs). Does not explicitly state when not to use it, but the context is clear enough for an agent to decide.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial context beyond that: internal checks (monotonicity, partition-sum), placeholder filtering, similarity threshold, the fill-check mechanism, and a warning not to trade when realizable edge is ≤ 0. This is far richer than the annotations alone.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and usage modes. Every sentence carries operational detail, and the formatting makes the complex content navigable rather than a wall of text.

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

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

With no output schema, the description fully explains the response structure: opportunities[] with fields, partition_check object, and fill-check outputs. It also covers edge cases (null signals, skipped_low_similarity, placeholders_filtered) and even names the sibling tool for custom sizing. For a complex arbitrage tool, this is exceptionally complete.

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

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

Although schema coverage is 100% and both parameters have descriptions, the tool description adds significant meaning: it explains the difference between single-event and cross-event modes, provides concrete example slugs and seed questions, and clarifies what happens in each mode (e.g., walks child markets, runs comparator on union). This goes well beyond the schema.

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

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

The description opens with a clear verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then enumerates three distinct modes (trending_scan, event, topic), each with a specific scope, which distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also explains which mode is recommended for a specific market and cross-references polymarket_fill_risk for custom sizing, giving clear 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 only declare read-only, open-world, idempotent, and non-destructive traits. The description adds substantial behavioral context: result caching at the KV level, segmented response with model-specific algorithms, diagnostics for why segments are empty, the 24h-move warning about edge already priced in, and specific exclusion of Fed bets due to unreliable signals.

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 extremely long and dense with niche details like per-sport alpha values (tennis 1.02, soccer 1.10, MMA 1.15), placeholder-slug filters, and Run 8 historical gate relaxations. While logically front-loaded with the core purpose, much of this detail is not necessary for tool selection or invocation and could be relegated to output documentation.

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 thoroughly detailing response top-level fields (by_segment, fed_candidates, _diagnostics), edge metrics (edge_pp_net, kelly_fraction, liquidity, spread), and the funnel counters for empty segments. It also covers caching behavior, making the tool's runtime characteristics fully transparent.

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

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

All 9 parameters are already described in the schema, yet the description adds deeper context: it explains the purpose of 'tradeable-edge knobs', clarifies that min_kelly doesn't apply to partition arbs while min_partition_leg_kelly does, and details how slippage is subtracted from raw edge before ranking. This goes well beyond the schema's individual parameter descriptions.

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

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

The description opens with a clear, specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also positions the tool for a concrete use case ('what should I bet on today'), distinguishing it from sibling tools like 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 it is 'built for what should I bet on today' and explains how knobs like min_liquidity/max_spread_pp filter opportunities. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for an agent to select it for edge discovery.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes far beyond by explaining response structure (tracked, expired, snapshot_dates), snapshot gaps due to cache-miss, TTL limits, decay calculation method, and the meaning of negative values. No contradictions with annotations; the description adds rich behavioral context.

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

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

Although long, the description is front-loaded with a one-line purpose, then clearly labeled sections (Args, RESPONSE, LIMITS). Every sentence provides necessary detail—parameter semantics, response fields, and limitations—without fluff. The structure makes dense information scannable 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 takes on full responsibility for explaining return values, and it does so thoroughly: tracked, expired, and snapshot_dates each get definitions and caveats. It also covers limitations (TTL, snapshot enablement, daily closes) and edge cases (gaps mean no scan). For a telemetry tool with this complexity, the description is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: days is described as 'lookback, default 14, max 30' while schema also mentions clamp 2-30, and window is framed as 'snapshot family' with examples from schema. It clarifies how parameters map to snapshot data, adding value over the schema alone.

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+resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers what the tool does—tracking edge longevity and decay—and differentiates from sibling tools like polymarket_edges by focusing on time-series behavior rather than 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?

The description implicitly states when to use this tool: when you need to know how long an edge has existed and whether it is shrinking, contrasting fresh vs. old wide edges. It does not explicitly name alternative tools or provide 'when not to use' exclusions, but the context strongly implies usage scenarios and distinguishes from the base edges 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 declare readOnlyHint/openWorldHint/idempotentHint, and the description adds rich behavioral detail: walk-the-ladder execution, mode-specific returns (top_of_book, vwap_fill_price, slippage_pp, verdict), basket-level overround capture, and the 'forced_directional_risk' naming of risky legs. It also warns about partial-fill failure modes—context far beyond the annotation flags. 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 dense yet well-structured: a one-line purpose, then REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence carries practical information; it is front-loaded with the core purpose and mode requirements. Length is justified by the tool's two-mode complexity.

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

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

With no output schema, the description carries the burden of explaining return values—and it does so thoroughly for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, plus basket-specific theoretical_sum, realizable_sum, capture_ratio, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also notes the USD threshold for use, making the tool fully usable without external references.

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 meaning beyond field names: it explains mode-dependent semantics (size_usd as spend on buys vs target proceeds on sells vs settlement notional in basket), defaults, clamp range (10–1,000,000), and REQUIRES one of market/event. This substantially enriches the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly naming polymarket_arbitrage and polymarket_edges as use-case triggers in the 'USE THIS' sentence.

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

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

Explicitly states when to use: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (thin books not capturable, partial fills create unhedged directional risk), giving clear context for when this tool is needed over alternatives.

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

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

Annotations already mark readOnlyHint=true and idempotentHint=true, but the description adds substantial behavior beyond that: compatibility_warning trigger conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and a candid caveat that most pre-mapped topics currently return warnings. 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?

Long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every section contributes operational information with no filler, though the density pushes the limit of 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?

No output schema exists, so the description correctly carries the full burden of explaining return values: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment fields, and skip counters. It also gives realistic expectations about pre-mapped topics, making it complete for this 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?

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds mode semantics: topic auto-fetches a pre-mapped event, while explicit kalshi_event_ticker and polymarket_event_slug create custom pairings and override the topic side. This clarifies the relationship between optional parameters 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?

Opens with specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling Polymarket-only tools by emphasizing the cross-venue comparison and same-question requirement. The two-mode structure is also stated up front.

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?

Describes two modes (topic shortcuts vs explicit ticker/slug) and gives actionable cautions: 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so' and 'pre-mapped ≠ tradeable'. It doesn't explicitly name sibling alternatives or state when to avoid this tool, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds return behavior ('Returns attribute rows (and geometry)') and a practical sampling tip, which is useful beyond the annotations. No contradictions found.

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

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

The description is two sentences, front-loaded with the main purpose and parameters. The second sentence is a valuable, non-redundant tip. No filler or wasted words.

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

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

For a read-only query tool with high schema coverage and safety annotations, the description covers the essential return type (attribute rows and geometry) and gives a quick-start example. It could mention potential errors or external service behavior, but overall it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by summarizing the SQL-like semantics of 'where' and the combination of where="1=1" with out_fields="*" for sampling, which is a meaningful usage pattern not fully explicit in the schema.

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

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

The description clearly specifies the verb 'Query' and the resource 'ArcGIS Feature Service / Map Service layer', and explicitly ties it to 'search_datasets' for provenance. It distinguishes itself from siblings like layer_info (metadata) and search_within (spatial search) by focusing on layer querying by URL.

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

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

The description provides a clear context: querying a layer obtained from search_datasets, and even gives a concrete sampling pattern with where="1=1" and out_fields="*". However, it does not explicitly state when NOT to use this tool or name alternatives, so it falls short of a full 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the behavior of omitting the key to list all entries, which goes beyond annotations.

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

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

Three sentences, each earning its place: core functionality, usage examples, scoping, and sibling pairing. 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?

For a simple one-parameter retrieval tool with no output schema, the description covers purpose, usage, scope, and related tools completely. The agent has everything needed 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?

Input schema fully describes the single optional `key` parameter with the omit-to-list-all behavior. The description reinforces this but adds little beyond what the schema already states, so baseline 3 applies.

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

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

The description clearly states the tool retrieves values saved via remember, with an optional list-all-keys mode. It distinguishes itself from sibling tools (remember saves, forget deletes) by explicitly naming the pairing.

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

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

Provides explicit usage context: look up previously stored context without re-deriving it, and mentions when to use siblings (remember, forget). This gives the agent clear decision guidance.

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

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

The description directly contradicts the readOnlyHint annotation by stating that setting mark_read:true flags events as read, which mutates the persisted feed state. This is a state-changing behavior, and the annotation indicates a read-only operation, so the description fails to align with the annotation.

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

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

The description is three sentences, front-loaded with the primary purpose, then return payload details, filtering options, mark_read behavior, and an alternative access endpoint. Every sentence earns its place; no filler or redundancy.

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

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

For a read-oriented tool with five parameters and no output schema, the description covers what is returned, how to filter, the mark_read side effect, and even provides an external endpoint. The main shortfall is the annotation contradiction, which prevents a perfect score, but structurally it is nearly complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful context beyond the schema: it provides a concrete example for type ('sec_8k'), clarifies the meaning of since as an ISO timestamp, and explains the behavioral effect of mark_read on subsequent calls. This elevates 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool returns (most recent alerts with source, citation_uri, raw payload) and distinguishes it from sibling tools like list_subscriptions and recent_changes by focusing on the persisted alert 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?

Provides clear usage context: filtering by type and since, using mark_read to make subsequent calls return only newer events, and notes that polling works fine. It also gives an alternative access method via HTTP for scripts/dashboards, though it does not explicitly name sibling tools or state 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?

Despite strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavior: multi-source fan-out, GDELT→GNews fallback with conditions, USPTO soft-fail, and output including citation URIs. This goes well 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?

Although long, every sentence adds distinct value: use cases, source details, fallback logic, parameter formats, return structure, and alternative tool. It is well-organized and front-loaded with the core purpose.

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 multi-source architecture and lack of output schema, the description thoroughly covers the return value (grouped changes, total count, citation URIs), fallback behavior, and source reliability. It is complete for an agent to select and invoke this tool correctly.

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

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

Schema covers all three parameters clearly, but description adds valuable examples for 'since' (ISO vs relative) and for 'value' (ticker vs CIK), plus typical monitoring suggestion. This exceeds the baseline for 100% schema coverage.

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

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

The description clearly states this is a change feed for a company over a time window, with concrete example queries ('What's new with X'). It distinguishes from sibling entity_profile by noting when to use the static profile instead.

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

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

It gives explicit use cases, mentions fallback behavior, and directly states when to use entity_profile instead. The 'since' parameter guidance ('Use 30d or 1m for typical monitoring') adds practical usage context.

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

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

Adds meaningful context beyond annotations: storage is 'scoped by your identifier,' and persistence differs by auth state ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). This complements the annotations (idempotentHint, destructiveHint, etc.) 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 compact and well-structured: it starts with the core purpose, then usage contexts, storage details, and sibling references. Every sentence adds value with no fluff or repetition.

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

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

For a simple key-value store tool, the description covers all essential aspects: purpose, when to use, persistence/scoping, and relationship to recall/forget. No return value is needed, and the schema fully documents 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?

The schema already fully describes both parameters with examples and descriptions (100% coverage). The tool description itself does not add further parameter-level detail, so the baseline score applies.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It uses a specific verb ('save') and resource ('data'), and explicitly differentiates from siblings by mentioning 'recall' and 'forget' as complementary tools.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also names alternatives/related tools: 'Pair with recall to retrieve later, 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?

Annotations already state readOnly/idempotent/non-destructive, but the description adds significant behavioral context: internal cascading lookups, auto-disambiguation, and citation URI formats for outputs (pipeworx://edgar/... and pipeworx://rxnorm/...). This goes beyond the structured fields and helps the agent anticipate side effects and return shape.

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

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

The description is front-loaded with user-facing examples and intent, followed by compact, structured type details. Every sentence earns its place—no filler. It uses a clear 'SUPPORTED TYPES' section and closes with a concrete benefit ('replaces 2-3 manual lookups').

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 what the tool returns for each supported type, including citation URIs. It covers accepted input forms and disambiguation behavior. For a simple 2-param tool with strong annotations, this is complete enough 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% (both params described), so baseline is 3. The description adds extra nuance beyond the schema by noting 'accepts ticker, CIK, or company name as input — auto-disambiguated' and specifying what each type returns (e.g., for company: ticker + CIK + name + citation). This enriches parameter understanding without repeating schema verbatim.

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

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

The description states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It also gives concrete examples ('What's the ticker for…') and distinguishes itself from sibling tools by focusing on identifier lookup, not profile/info retrieval.

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: 'Use FIRST whenever you have a name but need an ID.' It also clarifies scope by listing supported types (company, drug) and says the tool 'replaces 2-3 manual lookups,' giving the agent a clear when-to-use signal in the context of other 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?

Annotations already flag readOnly/openWorld/idempotent/non-destructive. The description adds process details (probes each entity, ranks by score, surfaces most/least recognized) and return shape (score, confidence, signal density), which goes beyond the safety profile. It does not mention auth/rate limits, but those are not contradicted and the schema carries the API key info.

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 with no filler. The first sentence states the core action, the second explains the mechanism, and the third gives a concrete use case and return format. All sentences earn their place.

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

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

The description covers purpose, process, use case, and return fields, making the tool's behavior comprehensible without an output schema. It doesn't explain edge cases like the optional models/_apiKey behavior in prose, but the schema already documents those, so the coverage is adequate for this complexity.

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

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

Schema covers 100% of parameters with descriptions, including the distinction that the first entity is the 'subject'. The tool description does not add any additional param-level meaning beyond what the schema already provides, so it stays at the baseline 3.

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

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

Description states 'Compare AI visibility across multiple entities side-by-side' – a specific verb+resource. It further distinguishes from sibling tools by mentioning it probes via ai_visibility_check, ranks by score, and tallies most/least recognized, narrowing to competitive AI-marketing audits.

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 use context ('competitive AI-marketing audits') and an illustrative question. It implies the single-entity tool ai_visibility_check for individual checks by saying it 'probes each entity ... with ai_visibility_check', but doesn't explicitly say 'use this instead of X when you have multiple entities', so no explicit exclusion/alternative.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description goes above the annotation baseline by disclosing composite fan-out behavior, latency characteristics ('bundlephobia's first measurement on a new version can take 5-30s'), and graceful degradation ('sources_failed will list it if it times out, the rest still returns'). These behavioral traits are valuable and not inferable from annotations alone.

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

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

The description is front-loaded with the core identity, then systematically covers usage, return fields, ecosystem scope, and failure behavior. While a bit longer than average, every sentence contributes new, actionable information. The structured ordering (purpose → use → outputs → limits → exceptional behavior) makes it easy for an agent to parse.

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

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

There is no output schema, so the description fully specifies the return payload: summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min/gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and alternative versions. It also covers partial failure semantics and ecosystem constraints, making the tool's behavior well-understood without any additional 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?

The input schema has 100% description coverage for both parameters (package and version), including scoped package syntax and default-to-latest behavior. The description does not add further parameter-level detail beyond the schema, so the baseline of 3 is appropriate; the schema already carries the semantic weight.

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

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

The description opens with a specific, compound purpose: 'Composite "should I add this npm package to my project" check in ONE call'. This clearly names the resource (npm dependency) and action (scan/check), and distinguishes it from sibling tools like validate_claim or scan_competitor_ai_presence by listing unique data sources (deps.dev, bundlephobia) and outputs (license, advisories, bundle size).

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear usage boundaries and redirects to a more appropriate tool for non-NPM ecosystems.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which already convey the safety profile. The description adds useful behavioral context: it returns specific fields (name, summary, record_count, owner/org, feature service URL) and indicates the tool is for open geospatial datasets. However, it doesn't say anything about pagination or rate limits, which would be extra value, but annotations suffice for core transparency.

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

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

The description is two sentences: the first concisely states purpose and scope, the second lists return fields and the chaining action. Every word adds value, no redundancy, and it's appropriately sized relative to the tool's simplicity.

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

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

Given no output schema, the description compensates by naming the exact fields returned and the chaining recommendation. The tool is a search/discovery read operation, so it doesn't need to explain side effects. The only slight gap is lack of mention of pagination, but with 1-50 limit and no required params, the context is sufficient for a candidate selection 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?

Schema description coverage is 100%, with each parameter (limit, query, org_id) having a meaningful description. The tool description adds context about the default org (City of Austin GIS) and that query is keyword-based, but it doesn't repeat parameter details beyond that. Baseline 3 for high coverage, with a slight bump for the description's note that 'query' can be multiword and the default scope, which supplements the schema.

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

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

The description clearly states a specific verb ('Search') and resource ('City of Austin GIS open geospatial datasets'), and enumerates content areas. It distinguishes itself from sibling tools like query_layer and layer_info by explaining its role as a discovery step and explicitly mentioning that the returned URL is to be passed to those tools.

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

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

The description provides explicit usage guidance: use this tool to find datasets by keyword, and then pass the returned Feature Service URL to query_layer / layer_info. It positions the tool as a discovery precursor, making the appropriate context clear and implicitly distinguishing it from tools that operate on a specific layer.

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

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses technical behavior: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging. These are meaningful operational details that help the agent predict results and limitations.

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 but not bloated. The first sentence delivers the core purpose, the second explains when to use it, and the third provides technical context. Every clause adds value, though the final sentence is fairly long with multiple clauses; still, it is well-structured and front-loaded.

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

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

Given no output schema, the description fully covers what the agent needs: input requirements, result shape (passages with character offsets and similarity scores), use case, algorithmic details, and input limits. It is complete for a search tool with 3 parameters and rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'text' parameter's practical role ('the text you already pulled'), giving concrete example queries for the 'query' parameter, and reinforcing the char limit with truncation behavior. It does not fully restate the schema but enhances it with usage context.

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 'search' with a clear resource ('inside a fetched record') and explicitly contrasts with sibling ask_pipeworx_grounded. It clearly states the tool's function: semantic search over already-fetched text with passage-level results, distinguishing it from other search/query tools.

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

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

Provides explicit guidance on when to use: when the record is too big to fit in the prompt, to save context and return only relevant passages. It also names the complementary alternative ask_pipeworx_grounded and explains the workflow ('fetch with the gateway, ground over the relevant passages instead of the whole document'), giving clear usage direction.

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

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

Annotations already mark this as non-read-only, idempotent, and non-destructive. The description adds substantial behavior: returns the new subscription id, account restrictions, webhook signing secret shown once, SMS verification and daily cap, and auto-disable after failures. No contradiction with annotations.

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

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

The description is front-loaded with purpose and prerequisites, then systematically covers types and delivery channels. It is dense but well-organized; every sentence adds value, though it is longer than strictly necessary for the information conveyed.

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 and high complexity, the description omits two of five enum types (patent_grant, clinical_trial) and the webhook delivery channel, both present in the input schema. This could mislead an agent about supported subscription options. Return value is covered, but the gaps are significant.

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

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

Schema coverage is 100% with rich parameter descriptions for params and delivery. The description repeats some examples (sec_8k items, polymarket topic, fred series_id) but adds little beyond schema; the phone-verification note is already implied in the delivery.sms schema description. Baseline 3 is appropriate.

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

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

Description opens with 'Create a proactive monitoring subscription to a live-data event stream', using a specific verb and resource that clearly distinguishes it from siblings like list_subscriptions or unsubscribe. It then enumerates concrete subscription types and delivery channels, reinforcing its role.

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

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

Specifies a prerequisite ('Requires a Pipeworx OAuth account – anonymous + BYO cannot persist subscriptions') and clarifies the action is for creating subscriptions. It does not explicitly contrast with alternatives, but the context makes it clear and no exclusions are given.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world traits. The description goes beyond by disclosing the dynamic nature ('drawn from the live catalog of thousands of tools'), the return structure (category-bucketed example questions with tool+argument shape), and that omitting the topic gives a 'full spread'—all meaningful behavioral context.

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

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

The description is longer than typical, but every sentence contributes: it leads with relatable example queries, states the core purpose, enumerates categories, describes the return value, and gives call variants. It is front-loaded and information-dense, though slightly verbose; a tighter second half could earn a perfect score.

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

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

Given the tool's complexity (one optional parameter, no output schema), the description fully covers what it returns, when to use it, and how to invoke it. It answers the likely questions an agent would have about this onboarding tool, making it contextually complete.

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

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

Although the input schema already describes the optional `topic` parameter with an enum-like list, the description adds concrete examples ('finance', 'pharma', 'betting'), maps them to the category names, and explains the default behavior when the parameter is omitted ('Call with no arguments for the full spread'). This goes well beyond the schema's coverage.

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

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

The description clearly identifies the tool as the 'onboarding entry point' for discovering what to ask Pipeworx, with a specific verb ('Returns category-bucketed example questions') and resource. It distinguishes itself from siblings by mentioning it maps questions to 'exact tool + argument shape' from the live catalog, and it names related meta-tools explicitly.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains two invocation modes (no arguments vs. passing a topic), which acts as clear usage direction.

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

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

Beyond annotations, the description adds key side-effect details: ownership enforcement ('you can only cancel your own subscriptions'), and the deactivation policy ('row is deactivated, not deleted') with a link to recent_alerts for historical events. These clarify exactly what the mutation does and its persistence implications, which is valuable context not present in the annotations.

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

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

Two concise sentences: the first states the primary action and input, the second provides necessary behavioral caveats. No redundant wording, and each sentence carries essential information.

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

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

For a simple one-parameter mutation with no output schema, the description fully covers what happens, who can do it, and the resulting state. The annotation hints cover idempotency and destructiveness, and the description adds ownership and historical data retention. This is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for the single parameter ('Subscription id (uuid) returned by subscribe.'). The description only says 'by id', adding no extra meaning beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription') with an explicit identifier ('by id'). It clearly distinguishes the tool from siblings like subscribe and recent_alerts by noting the deactivation behavior retains historical events.

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

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

The usage context is implied: use this to cancel a subscription. Ownership enforcement is stated, but there is no explicit mention of alternatives or when not to use it (e.g., to re-enable, use subscribe). It does not say to list subscriptions first, though that is a natural precursor. This is adequate but not explicit about 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 provided annotations (read-only, open-world, idempotent), the description reveals routing logic (SEC EDGAR fast path vs grounded pipeline), exact percent-delta math, and the judgment behavior. It also specifies the return payload (verdict, value, citation, reasoning). This is useful behavioral context not captured by the annotations, though it does not mention potential failures or limitations.

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

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

The description is a single dense paragraph; every sentence adds value—triggers, purpose, routing, output, and efficiency. It is slightly long but front-loaded with trigger phrases and a clear purpose statement, making it easy to scan. A more concise version could trim some redundancy, but structure is good.

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 the return value (verdict enum, actual value, citation, reasoning). It covers routing, scope, and behavior for both financial and non-financial claims. For a two-parameter tool, this is highly complete and leaves no major gaps in understanding what the tool does or returns.

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?

Both parameters are fully documented in the schema (100% coverage), so the description is not required to add parameter details. The description does reference the claim type and tolerance concept, but the schema examples carry the semantic load. This aligns with the baseline score for high coverage.

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

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

The description opens with trigger phrases like 'fact check' and 'verify the claim that…', then states it is 'natural-language claim verification against authoritative sources'. It clearly distinguishes from sibling tools by scoping to factual claims and specifying the financial vs non-financial routing. The verb 'verify' plus the claim resource is specific.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It details the two internal paths and notes it replaces 4–6 sequential calls, making it the clear go-to for claim verification. However, it does not name alternative tools or state when not to use it, so slightly below top.

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