Arcgis Abbotsford

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

Even with annotations already declaring readOnly/openWorld/idempotent, the description adds valuable behavioral detail: the default model (Workers AI Llama-3.3-70b) is free, using Anthropic requires a BYO key with direct payment, and the response structure is outlined. It also mentions how _apiKey is handled ('passed straight through'), which is important for cost and privacy expectations.

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

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

Three sentences, each earning its place: function and output, default model and optional Anthropic integration, return format and use cases. It is front-loaded with the most important information and contains zero filler.

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

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

With no output schema, the description explicitly states the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers model options, cost, use cases, and required parameter (entity). For a 4-param tool with no output schema, this is remarkably complete.

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

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

The input schema already covers all parameters at 100% coverage, so the baseline is 3. The description enriches this by explaining the default model behavior and the 'BYO key' payment implication for _apiKey, adding meaning beyond the schema's basic descriptions. This lifts it slightly above the baseline, though the schema still does most of the heavy lifting.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs'), then defines the output (visibility score 0-100 per model). It clearly distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on individual LLM awareness scoring rather than a broader competitor scan. The scope (business/brand/product/topic) is explicit.

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

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

The description gives explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not state when not to use it or name alternatives, so it stops short of full exclusionary guidance. However, the context is clear and actionable enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it discloses that the tool routes internally, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. This enriches the agent's understanding without contradicting 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 dense but front-loaded with the most important routing instruction ('PREFER OVER WEB SEARCH') and includes valuable examples and exclusions. The text is slightly rambling in places, with a long conditional clause about alternatives, but nearly every sentence adds useful information for tool selection.

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, the description covers scope, trigger language, examples, citation output, and related tools effectively. The lack of an output schema is partly mitigated by the mention of structured answers and citation URIs. Minor gaps remain around edge cases like multi-part questions and any potential limitations, but overall it is well-rounded.

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

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

The input schema has 100% description coverage and thoroughly documents the main 'question' parameter plus its aliases. The description does not add any new parameter-level detail beyond saying the tool 'fills arguments' internally, so it earns the baseline score rather than exceeding it.

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

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

The description clearly states the tool's function: it routes natural-language questions to one of 5,767 tools across 1,506 verified sources and returns a structured answer with stable citation URIs. It also distinguishes itself from web search and sibling tools by listing the exact domains it covers (SEC filings, FDA data, economic stats, patents, 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?

The description explicitly instructs the agent to prefer this tool over web search for a broad range of factual queries, lists trigger phrases like 'what is' and 'look up', and provides concrete examples. It also names alternatives ('ask_pipeworx_grounded' for a single citable answer, 'deep_research' for broad multi-part questions), giving clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, and the description adds meaningfully beyond that: the experimental status, live candidate switching, and the fact that the last candidate was retired on outcome evidence 2026-07-26. It also clarifies this is a full working router with no fallback — a useful disambiguation against the 'beta' label. No contradiction with annotations; the safety profile is consistent.

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 dense sentences, each carrying distinct information: identity, current state, usage instruction, and fallback clarification. The beta-status nuance justifies the length, and the key fact (identical to ask_pipeworx) 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?

For a tool with 6 params (5 aliases), full annotations, and no output schema, the description is complete: an agent knows it is the experimental router, what arguments it accepts (via schema), what response shape to expect ('same response shape'), and what the beta status implies. The only minor gap is not defining what happens when a candidate is under test beyond 'candidate routing improvements.'

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

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

Schema coverage is 100%, with each alias (q, text, input, prompt, query) documented as an alias for 'question.' The description refers to 'same arguments' as ask_pipeworx rather than repeating schema content, which is appropriate; with full schema coverage, the baseline 3 applies.

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

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

The description states precisely what the tool is — a beta version of ask_pipeworx, an identical universal router spanning 5,767 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx sibling and the grounded variant by its experimental status, so an agent can tell them apart without opening either schema.

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

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

Explicitly instructs the agent to 'use it exactly like ask_pipeworx when you want the newest routing,' and explains that candidate routing improvements are compared against the stable router. It also notes that no candidate is currently active, so behavior matches ask_pipeworx exactly right now. It doesn't, however, address when the grounded variant would be preferable, leaving some selection nuance to the agent.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the refusal behavior with exact reasons, the 'ONLY what the tool result contains' constraint, and the extra LLM call cost. This is rich behavioral context that annotations do not 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 well-structured: it leads with purpose, explains the mechanism, details return/refusal formats, then gives usage guidance and cost tradeoff. Every sentence carries necessary information without fluff, front-loading the critical distinction.

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 high-stakes tool with no output schema, the description fully covers return shape (including refusal reasons), usage context, and cost trade-off. An agent has all information needed to decide and invoke correctly.

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

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

Schema covers all 6 parameters with descriptions (100% coverage), so the description adds no parameter-level detail. Baseline 3 is appropriate; the aliases are self-explanatory and no further semantics are needed.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism (same routing as ask_pipeworx but extracts answer using only tool result). It explicitly distinguishes from ask_pipeworx by emphasizing grounded extraction with evidence and refusal reasons, making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also says 'prefer ask_pipeworx for casual lookups' and notes the extra cost, clearly guiding selection among siblings.

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

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

The description goes far beyond the annotations, detailing classifier categories, fan-out behavior, resolver contract fields, status codes (e.g., low_confidence_match, market_closed_or_inactive), tradeability warnings, cancellation rule risks, and news fallback behavior. This is consistent with the readOnly/idempotent/non-destructive annotations and richly covers operational edge cases.

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

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

The description is long but highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and no fluff. It front-loads the core purpose in the first sentence, then elaborates systematically. The length is justified given the tool's complexity, though it is not succinct.

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?

Since there is no output schema, the description carries the full burden of explaining return values and behaviors. It comprehensively documents response shapes, resolver confidence, parent events, news fallbacks, safety modes, and resolution-rule risk, making it fully complete for a tool with 3 parameters and high 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 input schema already covers all three parameters with descriptions, examples, defaults, and enums (100% coverage). The description does not add significant parameter-level meaning beyond what the schema provides, and the baseline for full schema coverage is 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's function: researching a Polymarket bet by pulling Pipeworx data, resolving the market, classifying the bet, fanning out to data packs, and returning an evidence packet plus market-vs-model comparison. This specificity distinguishes it from sibling tools like polymarket_edges or deep_research, despite not naming them.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear context on when to invoke the tool but does not explicitly state when-not-to-use or recommend alternative sibling tools, so it falls short of a 5.

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

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

Annotations already convey read-only/idempotent safety. The description adds rich behavioral detail: data sources (SEC EDGAR/XBRL, FAERS, FDA), specific metrics pulled for each type, handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This goes well beyond the annotations.

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

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

The description is long but information-dense and well organized, front-loading examples and use cases. Every sentence adds meaningful guidance (when to use, data sources, sorting, citations). Slight over-length could be trimmed, but it earns its space for a tool with this 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?

Despite no output schema, the description covers return format (paired data + citation URIs), sorting, entity type behavior, fiscal year handling, and the efficiency benefit. Combined with the annotations and full schema coverage, this is a complete picture for the agent to invoke the tool confidently.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description enhances this by explaining what each type ('company' vs 'drug') yields in terms of data sources and metrics, which adds value beyond the schema. Minor gap: no additional disambiguation of value formats beyond schema descriptions.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. Specific trigger phrases and resource types distinguish it from related single-entity tools like entity_profile.

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

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

The description explicitly states when to use the tool (comparison queries such as 'X vs Y', 'which is bigger', 'rank these companies') and says to always prefer it over sequential single-pack lookups. It could be stronger by naming a specific alternative tool, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: account/paid-plan requirements, 'explicit gaps[] for facets the data couldn't answer (never invented)', and the findings packet structure with stable pipeworx:// citations. This goes beyond the annotations, though it omits latency and failure 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 severely bloated: the same paragraph is repeated many times verbatim, with no sectioning or progressive structure. Almost every word after the first occurrence is redundant. This is the opposite of concise and fails the 'every sentence earns its place' test.

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

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

Given the tool has only 2 parameters, 100% schema coverage, safety annotations, and no output schema, the description covers the key contextual needs: return packet fields (verbatim evidence, confidence, source, fetched_at, citation, gaps[]), auth requirements, and when to prefer ask_pipeworx. Missing details like latency or error handling are minor. The repetition doesn't remove content but does hurt scannability.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds the decision-relevant constraint that depth:'thorough' requires a paid plan, and reinforces that broad/multi-part questions are acceptable ('Broad/multi-part is fine — decomposition is the point' is implied by the examples and schema). This parameter-specific extra information justifies a 4.

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

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

The description states a clear verb and resource: 'grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call', and distinguishes itself from ask_pipeworx with 'For a single lookup use ask_pipeworx instead'. However, the text repeats the same paragraph many times and contains garbled tokens, which slightly muddies an otherwise strong purpose statement.

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

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

Provides explicit routing conditions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead', plus a clear best-fit statement: 'Best for broad/multi-part questions over structured data'. It does not mention other sibling alternatives like ask_pipeworx_grounded, but the primary alternative guidance is solid.

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

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

Annotations already declare readOnly, idempotent, non-destructive; description adds that results include full input schemas with curated examples, ready to call directly without second lookup, and the intended first-step usage pattern. This goes beyond annotations but doesn't address any performance/rate-limit concerns.

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 adding value: purpose, domain coverage, and return format/usage heuristic. The long domain list is relevant but slightly exhaustive, keeping it to a 4 rather than 5.

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

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

For a meta-tool, the description covers what it does, when to use it, what it returns (including schemas and examples), and how it fits into the workflow. No output schema is needed given this level of detail.

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

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

Schema covers all 6 parameters with descriptions and examples; the description itself mostly restates the domain list, so it adds marginal value. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool finds tools by natural language description of data or task, and enumerates covered domains, distinguishing it from sibling tools like search_datasets or search_within which operate on data rather than the tool catalog.

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 when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', giving clear criteria and differentiation from direct-answer 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?

Heavily complements annotations: readOnlyHint, openWorldHint, idempotentHint, destructiveHint are all declared, and the description adds substantial context — the fan-out across sources, soft-fail on patents, expected-empty sections, resolved:false for private companies, and sources_failed handling. No contradiction, and the extra behavior is clearly spelled out.

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 justified — every sentence adds operational detail (data sources, return sections, failure semantics). Front-loaded with examples and 'ALWAYS PREFER' guidance. Could trim redundancy (e.g., repeated phrasing about `type`), but overall it's dense and useful without fluff.

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

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

Comprehensive for a complex tool with no output schema: explains every return section (cik, recent_filings, fundamentals, patents, contracts, fda_products, hiring, news, LEI), what empty sections mean, failure handling, input parsing, and private-company behavior. Nothing an agent needs to call it or interpret results is missing.

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

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

Schema already describes both parameters at 100% coverage, so baseline is 3. The description adds meaningful nuance: type is interchangeable, value can be ticker/CIK/name, and explains resolution behavior. This elevates it above the 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?

States a specific verb ('full cross-source profile') and resource ('US public company'), clearly differentiating from siblings like resolve_entity (which only resolves) and compare_entities (which compares). The examples of user queries ('Tell me about X', 'company profile for Microsoft') make the purpose unmistakable.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', naming the alternative (chaining individual lookups) and the condition. Also distinguishes from narrow use cases (single filings, news) by specifying that this is the one-call holistic option.

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?

While annotations already declare destructiveHint=true and idempotentHint=true, the description adds context about 'previously stored memory' and clearing 'sensitive data the agent saved earlier', which helps the agent understand what the operation affects. 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 two sentences, front-loaded with the core purpose and followed by usage guidance. Every word earns its place; no filler.

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

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

For a simple one-parameter tool with good annotations and no output schema, the description fully covers purpose and usage. It also situates the tool within the remember/recall workflow, making it complete for an agent to use effectively.

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% as the property 'key' has the description 'Memory key to delete'. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key. It uses the specific verb 'delete' and resource 'memory', making it distinct from sibling tools like 'remember' and 'recall'. The phrase 'by key' further clarifies the operation.

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

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

The description explicitly lists when to use the tool: when context is stale, task is done, or to clear sensitive data. It also mentions pairing with 'remember' and 'recall', giving workflow context. However, it does not explicitly state when not to use or mention alternative deletion tools, but the conditional guidance is strong.

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

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

Discloses the full behavior: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. Adds deployment context ('ready to drop at site-root/llms.txt') beyond the annotations, which already declare read-only, idempotent, non-destructive behavior. No contradiction with annotations.

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

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

Three sentences, front-loaded with a precise purpose, followed by mechanism and use cases. No filler; every clause contributes to understanding the tool's function and output.

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 low complexity, full schema coverage, and strong annotations, the description provides the missing output context (single text blob ready for site-root/llms.txt) and workflow details. This makes the tool adequately complete for an AI agent to select and invoke it.

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

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

Schema description coverage is 100%, with url described via example and max_links including default/max. The description's mention of extracting title/description/key links and output format adds context but does not significantly enrich parameter semantics beyond the schema, 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?

Description opens with a specific verb ('Generate') and resource ('production-ready llms.txt file for any URL'), and names the intended output format and consumers (AI crawlers). This clearly distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on producing the standard file rather than analyzing presence.

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

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

Explicitly lists 'Useful for' scenarios: indexing a client's site, drafting for own project, or auditing a competitor. This gives clear context for when to use the tool, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and side effects. The description adds the output composition (fields, geometry, record count, capabilities) but no additional behavioral context such as authentication needs, rate limits, or edge cases. It does not contradict annotations.

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

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

The description is a single, dense sentence that front-loads the main purpose and lists all key outputs without any filler. Every part earns its place, making it highly concise and well-structured.

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

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

The tool has a simple parameter set (1 param) and rich annotations, so the main missing piece is output structure. The description enumerates what is returned (fields, geometry type, record count, capabilities) but does not specify the exact JSON shape or potential error conditions. This is a minor gap given the tool's simplicity; the description is largely complete for agent use.

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

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

The input schema already provides a full description for the 'url' parameter (e.g., 'Feature/Map Service layer url, e.g. ".../FeatureServer/0"'), yielding 100% schema coverage. The description merely mentions 'by url' without adding extra semantics beyond what the schema supplies, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Get'), resource ('ArcGIS Feature/Map Service layer's schema'), and method ('by url'). It also lists the specific outputs (fields, geometry type, total record count, capabilities), which distinguishes it from sibling tools like 'query_layer' that likely query data instead of schema.

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

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

The description implies usage: if you need a layer's schema information, use this tool. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions. No explicit 'use this when...' or 'instead of...' guidance is given, so usage is implied but not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it returns only active subscriptions by default. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences: the first states the action and return fields, the second gives usage guidance. It is front-loaded with the core purpose, contains no fluff, and every sentence earns its place.

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

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

For a simple read-only list tool with one optional parameter, the description is complete: it explains what it does, what it returns, and when to use it. There is no output schema, so the explicit list of return fields is especially valuable. The annotations handle safety semantics, and the schema handles parameter details.

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 covers the single optional parameter include_inactive with a clear description, so schema coverage is 100%. The tool description does not mention this parameter, but it does not need to because the schema is self-sufficient. The baseline of 3 is appropriate since the description adds no extra parameter meaning beyond the schema.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly distinguishes the tool from siblings by focusing on listing, while siblings like subscribe/unsubscribe handle mutations. It also specifies the scope ('caller's') and the default filter ('active').

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use it in relation to adding or canceling subscriptions. However, it does not explicitly name sibling tools like subscribe or unsubscribe as alternatives, so it stops short of a perfect score.

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

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

The annotations are all false and provide no safety hints, so the description carries the full burden. It discloses the anonymous claim_token flow for later retrieval, rate limiting (5/day), free/no-quota status, and the team's daily digest cadence — all beyond the structured fields.

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

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

At roughly 150 words, the description is dense but each sentence adds a distinct piece of information (scope, use cases, token flow, rate limits). It is longer than ideal but justified by the tool's dual submit-inquire behavior and exclusion rules.

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

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

With no output schema, the description adequately explains the return behavior via claim_token and how to consume it later. It covers type selection, message content, scope constraints, and operational limits, making it sufficient for a low-complexity feedback tool despite lacking explicit success/error response details.

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%, providing parameter descriptions, but the description adds semantic guidance on how to form the message ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and explains the claim_token round-trip usage pattern, which is not in the schema.

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

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

The description opens with a clear verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates concrete trigger types (bug, feature/data_gap, praise). No sibling tool serves this feedback purpose, so it is well differentiated from the 30+ listed siblings.

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

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

Explicit when-to-use guidance is provided for each feedback type, and an explicit exclusion rule scopes the tool to Pipeworx-owned tools only, directing users to file external-server issues elsewhere, with a fallback disambiguation ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it's self-aggregating, derived from CF analytics-engine, no PII, just (pack, tool, count), and cached 5min-1h depending on window. This goes beyond what annotations provide.

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

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

The description is concise and front-loaded with the core purpose, followed by a compact bulleted list of use cases. Every sentence adds value: behavior, data source, privacy, and caching. No fluff or redundancy.

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

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

The tool is simple (one optional param), has rich annotations, and the description explains the output's high-level shape (top tools, packs, call volume) and caching behavior. There's no output schema, but the description provides enough for an agent to select and invoke the tool correctly.

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

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

The only parameter (window) has 100% schema description coverage, so the schema already handles semantics. The description reinforces this by mentioning the window in the first sentence, but adds no new parameter-level information beyond what the schema already includes.

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

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

The description opens with a specific verb+resource+scope: what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume over a recent window. It clearly distinguishes from siblings like ask_pipeworx (Q&A) and discover_tools (tool discovery) by focusing on aggregate usage trends.

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

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

The description provides three explicit 'Useful for' scenarios, giving clear context on when to use the tool (e.g., discovering hot data sources, confirming canonical tool choice). It does not mention alternatives or explicit when-not-to-use cases, but the use cases are concrete and actionable.

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

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

Beyond the readOnlyHint annotation, the description discloses internal logic: monotonicity checks, partition-sum validation, a Jaccard similarity threshold of ≥0.30, placeholder filtering with >20% placeholder fraction returning null, fill check against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. This is rich behavioral detail not present in 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 lengthy but well-organized with section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and enumerates modes, but some details are dense and could be trimmed or referenced to the schema. Still, most sentences add 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?

The tool is complex with multiple modes and no output schema, but the description explicitly outlines the response structure (opportunities[], partition_check fields), fill check semantics, and failure conditions like placeholders_filtered. It covers edge cases (realizable_edge_pp ≤ 0 warning) and provides enough behavioral detail to invoke and interpret results correctly.

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

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

Although the schema already describes both optional parameters, the description adds crucial usage context: the default no-arg behavior, the distinction between event and topic modes, concrete examples for each, and what each mode computes. It also mentions acceptance of full Polymarket URLs in the schema, while description provides slug 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 begins with a clear verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This distinguishes it from siblings by specifying the methodology and enumerating modes, while sibling tools like polymarket_edges and polymarket_fill_risk focus on edges and fill risk respectively.

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

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

The description explicitly lists three invocation modes (no args, event, topic) and when to use each, such as 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also directs users to polymarket_fill_risk for custom sizing, providing a clear alternative.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses granular behavioral details: model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure under by_segment, diagnostics for empty segments, caching behavior (1h at KV level), Fed note exclusion rationale, and the 24h-move warning. This is a rich, non-contradictory behavioral transparency.

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

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

The description is front-loaded with a clear purpose, but it quickly becomes a massive single-paragraph wall of text with many clauses, parentheticals, and dense jargon. It contains valuable information, but the lack of paragraph breaks or bullet points reduces scannability. It is appropriately sized for the tool's complexity but could be structured better.

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

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

Given there is no output schema, the description fully compensates by detailing the response top-level (by_segment, fed_candidates/fed_note, _diagnostics), explaining why segments can be empty (funnel counters, filter_skips), and covering all execution knobs. It also documents the caching behavior and edge qualifiers (edge_pp_net, kelly_fraction_half cap, liquidity/spread/volume). Nothing essential is left unexplained.

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

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

All 9 parameters have schema descriptions, so baseline is 3. The description adds extra meaning beyond the schema by explaining how min_kelly and min_partition_leg_kelly interact (partition arbs always have parent-level half-Kelly of 0), and why slippage_pp defaults to 0.3 with guidance to adjust based on book thinness. This elevates parameter understanding beyond field-level docs.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also clarifies the intended use case ('what should I bet on today') and positions itself against siblings by emphasizing Pipeworx disagreement and the 'without paging hundreds of markets' convenience.

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 opening sentence sets clear usage context: the tool is for discovering betting opportunities and saves agents from scanning many markets. The description elaborates on knob usage (min_liquidity, max_spread_pp, etc.) and response segments, but it does not explicitly name sibling alternatives or state when NOT to use this tool over related ones like polymarket_arbitrage.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses critical behavioral details: the 60-day snapshot TTL, that snapshots are written on cache-miss, that gaps in snapshot_dates mean no scan occurred, and that decay numbers are computed from daily closes rather than intraday. This adds significant value 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 longer than typical examples, but it is well-structured with explicit Args, RESPONSE, and LIMITS sections. Every sentence provides necessary detail, especially since there is no output schema to explain the return structure. It is front-loaded with purpose and remains highly informative without redundancy.

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

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

Given the lack of an output schema, the description comprehensively explains the response fields (tracked[], expired[], snapshot_dates[]), their meanings, and caveats like lifespan_days as a 'competition clock' and the limitation of history depth. It covers edge cases and limitations thoroughly, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, with both days and window already described in the input schema. The description repeats defaults and clamps but adds little new semantic meaning. The 'window' description in the schema already mentions 'snapshot family', and the description's additional context about defaults is redundant.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes from siblings by focusing on historical persistence ('how long has this edge existed and is it shrinking?'), which is not covered by tools like polymarket_edges that likely list 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 provides a clear use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains when the tool is valuable. It does not explicitly name alternatives or exclusions, but the context is strong enough to infer when to use it versus other edge-related 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 declare readOnly/openWorld/idempotent, which the description does not contradict. The description adds substantial behavioral context: it walks the order book, returns a verdict (clean|degraded|cannot_fill), highlights forced directional risk, and warns that partial fills convert an arb into an unhedged directional position—valuable 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 long but appropriately structured with SINGLE-MARKET and BASKET sections, bolded key terms, and no filler. Every sentence carries essential information about behavior, parameters, return values, or risk, justifying its length for a complex two-mode 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?

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It enumerates all returned fields for both modes, explains the difference between theoretical and realizable value, names the riskiest legs, and provides threshold guidance—enough for an agent to select and invoke the tool correctly.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant meaning: it clarifies that exactly one of `market` or `event` is required, explains `side` auto behavior in basket mode, and reinterprets `size_usd` as 'max spend on buys' vs 'target proceeds on sells' and as 'settlement notional S' in baskets—details not fully captured in the schema.

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

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

The description opens with a specific, meaningful purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by stating it should be used before executing their SELL/BUY-EVERY-LEG signals or trades above ~$500.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market and basket), when to use each, and why partial basket fills are dangerous, giving clear context for choosing 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?

Even though annotations already mark the tool as read-only and idempotent, the description adds substantial behavioral context: it discloses that matches are keyword-based rather than source-verified, that compatibility warnings can be non-empty even when pairs are returned, that spreads are gross of Kalshi fees, and that unknown leg types are never paired. This goes far beyond the structured annotations and honestly surfaces the tool's 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 thorough and front-loaded with the core purpose and mode distinction, but it is very long and at times repetitive, with dense parentheticals and repeated warnings about compatibility codes and temporal alignment. It earns most of its length because the tool is complex, but it could be tightened without losing key caveats.

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

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

Because there is no output schema, the description carries the full burden of explaining the response, and it does so comprehensively: it covers per-venue prices, top_spreads_pp, per-pair flags, compatibility codes, skipped/unknown legs, temporal alignment semantics, and the fees note. An agent has enough context to correctly interpret results and avoid over-trusting the spread.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond that by explaining how topic maps to auto-fetched events, how explicit ticker/slug overrides the mapped side, and that both modes run the same overlap matcher. This is useful but not dramatically deeper than the schema descriptions already provide.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the resource, the action, and the core output (probability spread in percentage points), and it clearly distinguishes this from single-venue tools like polymarket_edges or polymarket_arbitrage by emphasizing cross-venue comparison.

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

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

The description gives explicit guidance for choosing between the two operating modes: pre-mapped topic shortcuts for quick macro comparisons and explicit ticker/slug pairings for custom candidates. It also cautions that pre-mapped topics are not automatically tradeable, which helps set expectations, though it does not explicitly name alternatives or state when a sibling tool should be used instead.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds beyond annotations: it returns attribute rows and geometry, supports SQL-like where clauses and pagination, and clarifies the sampling approach. This is useful behavioral context.

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

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

Two sentences: the first states purpose and key parameters; the second gives a concrete usage tip. Front-loaded, no redundant content, every clause earns its place.

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

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

For a tool with no output schema, it adequately explains input origin (url from search_datasets), query capabilities, return shape (attribute rows + geometry), and a practical usage tip. It doesn't mention caveats like field syntax or results limits beyond schema, but the schema already covers those.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting the SQL-like nature of 'where', that results include geometry, and the '1=1'/'*' sampling idiom — info not fully captured in the schema definitions.

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

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

Description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url' — a specific verb and resource. It also references the source ('from search_datasets'), which distinguishes it from sibling tools like search_datasets and layer_info.

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

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

It implies a workflow: first find a dataset via search_datasets, then query it. The tip 'Use where="1=1" + out_fields="*" to sample' provides practical usage guidance. However, it doesn't explicitly name alternatives or note when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and mentions two operation modes, though it does not describe the return format or error behaviors.

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

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

The description is appropriately sized—four sentences, front-loaded with the primary action, and includes useful context, examples, and related tools without fluff.

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

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

For a simple one-parameter read-only tool with no output schema, the description covers purpose, usage scenarios, scoping, and sibling relations. It lacks an explicit return value description, but this is minor given the tool's simplicity.

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

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

Schema coverage is 100%, and the description's mention of omitting the key argument duplicates the schema's property description. No additional semantic value is provided beyond what the schema already states.

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

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

The description clearly states retrieval of a value saved via 'remember' or listing all keys, with concrete examples like user's target ticker or address. It distinguishes from sibling tools 'remember' and 'forget' by naming them 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?

Explicitly says 'Use to look up context the agent stored earlier' and instructs pairing with remember to save and forget to delete, providing clear guidance on when to use versus alternatives.

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

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

Annotations indicate read-only and idempotent behavior, but the description adds important context: mark_read mutates read state to affect subsequent calls, and the same feed is available at a public URL. This goes beyond the annotations without contradicting them, though the mark_read side effect is slightly at odds with the readOnlyHint.

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 focused, well-structured sentences. Each sentence adds value: purpose, capabilities, and behavior are all delivered without 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 list-style tool with no output schema, the description is remarkably complete: it explains the return payload, filtering options, mark_read state behavior, polling suitability, and alternative access. With annotations covering the safety profile, no critical information is missing.

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

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

The schema fully covers all five parameters, but the description adds real-world meaning with a concrete type example ('sec_8k'), clarifies the ISO timestamp format, and explains mark_read's side effect. This enhances understanding beyond the schema definitions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the return payload (source, citation_uri, raw event) and distinguishing it from sibling tools like list_subscriptions and subscribe by focusing on alert 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?

Provides explicit guidance on filtering by type and since, using mark_read to control future reads, and notes that polling works. It also offers an alternative HTTP endpoint for scripts/dashboards, giving context for when the tool is appropriate, though it doesn't explicitly state when not to use it.

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

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

The description discloses significant behavioral traits beyond the annotations: it fans out to multiple source APIs, states the GDELT→GNews fallback on rate limits or 5xx, and notes that USPTO patents soft-fail due to the PatentsView API sunset. It also mentions the parallel execution. This enriches the agent's mental model beyond what readOnly/openWorld/idempotent hints provide, with no contradiction.

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

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

The description is dense and thorough but not unnecessarily verbose. It front-loads with user-friendly question paraphrases, then lists the source fan-out, fallback logic, parameter formats, return structure, and an explicit alternative. There is some redundancy (e.g., repeating since formats), but each section earns its place given the tool's complexity.

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

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

The description provides a complete picture: the scope (company + time window), the upstream sources and their fallback behavior, the `since` parameter semantics, the return structure (changes[], total_changes, citation URIs), and a clear pointer to entity_profile for static needs. Given there is no output schema, the description fully compensates by specifying what is returned.

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

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

Although schema coverage is 100%, the description adds value by clarifying the 'since' parameter with examples ('7d', '30d', '3m', '1y') and a recommendation ('Use "30d" or "1m" for typical monitoring'). It also reiterates ticker or CIK formats for 'value' and confirms 'type' is limited to 'company'. These additions go beyond the bare schema field descriptions.

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

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

The description clearly identifies this as a change feed for a company over a time window, listing example queries and the data sources it covers (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from entity_profile, so the purpose is specific and well-differentiated from siblings.

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

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

The description explicitly says 'Use entity_profile instead when you want the static profile...' which is a clear alternative and a when-not to use this tool. The query examples and the note about ONE parallel call imply appropriate use cases, though it doesn't discuss alternatives like recent_alerts. This is strong 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 provide idempotentHint=true and readOnlyHint=false, and the description adds substantial context beyond them: key-value scoping by identifier, persistence differences between authenticated and anonymous sessions, and pairing with recall/forget. 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?

Four sentences, each carrying distinct value: purpose, when to use, storage model, and companion tools. No filler or repetition, and it is front-loaded with the core action.

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

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

For a simple two-parameter save tool with no output schema, the description covers what, why, when, storage behavior, and usage context with related tools. Nothing important is missing 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 description coverage is 100%, with clear descriptions for key and value parameters. The description briefly reinforces the key-value structure but does not meaningfully extend beyond the schema; baseline 3 is appropriate.

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

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

The description uses a specific verb+resource combination ('Save data the agent will need to reuse later') and clearly defines the tool's scope (key-value memory across conversations/sessions). It also distinguishes itself from sibling tools by framing this as the write counterpart to recall and forget.

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

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

The description gives explicit when-to-use context ('when you discover something worth carrying forward') with concrete examples, and names the paired retrieval/deletion tools (recall, forget). It lacks an explicit when-not-to-use statement, which keeps it from a 5.

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

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

The annotations already mark the tool as read-only/idempotent, and the description adds substantial behavioral context: internal cascading of multiple lookup endpoints, graceful degradation for LEI/FIGI enrichment, explicit unresolved-identifier handling, and non-equity instrument resolution. It also clarifies that ambiguous multi-match instrument names return figi_candidates instead of asserting a wrong answer. No contradiction with annotations.

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

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

The description is long but front-loaded with purpose and usage, then organizes details by supported types. Every sentence adds operational value, particularly the caveats about bonds, ISIN-to-LEI resolution, and unresolved identifiers. The density is justified by the tool's complex behavior and broad coverage.

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

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

Given the tool's complexity and the absence of an output schema, the description is unusually complete. It covers input forms, supported entity types, resolution sources, ambiguity handling, failure behavior, and enrichment fallback. An agent has enough information to select the tool and form a valid resolve_entity call without needing external documentation.

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

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

Even though schema description coverage is 100%, the description adds significant parameter-level meaning. It explains what each type supports, gives input examples for ticker/CIK/ISIN/name and drug brand/generic names, and provides crucial advice to pass only the entity name, never the full noun phrase, because trailing security-class words will fail the FIGI lookup.

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

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

The description states a specific verb and resource: it "resolve[s] a user-spoken NAME to the canonical/official identifiers other tools require as input." It also gives concrete utterance examples and distinguishes itself as the identifier-resolution tool among siblings like entity_profile and compare_entities by framing its output as input for other tools.

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

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

The description gives explicit usage context: "Use FIRST whenever you have a name but need an ID," and it enumerates trigger phrases such as "what's the ticker for…" and "look up the ID for…". It does not name sibling alternatives or explicitly state when not to use it, so it misses full exclusionary 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 discloses that each entity is probed via ai_visibility_check and results are ranked by score, with output including confidence and signal density. This adds behavior beyond the annotations (readOnly, idempotent) by describing the orchestration and return shape. It does not contradict 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?

Three sentences: purpose, mechanism, return and use case. No repetition or filler, every sentence contributes.

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

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

With a 100%-coverage schema and annotations indicating a safe, read-only operation, the description still provides essential output context by listing score, confidence, and signal density. It explains the probe-and-rank workflow. It lacks caveats about multiple sub-calls or API-key requirements, but these are covered by the schema.

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

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

The input schema already provides detailed descriptions for all four parameters, including entity semantics, model options, and context. The description only loosely refers to 'your brand + N competitors,' which duplicates the schema's explanation of the first entry as the subject. Therefore, it adds little 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 identifies a specific action: comparing AI visibility across multiple entities side-by-side. It mentions the sub-tool ai_visibility_check and the ranking behavior, distinguishing it from single-entity probes. The competitive marketing audit use case adds further clarity.

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 states the tool is 'useful for competitive AI-marketing audits' and implies comparison across entities, but it does not explicitly exclude alternatives like ai_visibility_check for single entities. The mention of probing with ai_visibility_check indirectly points to that sibling for one-off checks.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important real-world behavior: it fans out to multiple services, handles partial failures gracefully via a `sources_failed` field, and warns about 5-30s latency on first measurement. This adds significant context that annotations alone don't provide, and nothing contradicts 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 long but every sentence provides distinct value: purpose, trigger scenarios, output fields, ecosystem limitation, and failure behavior. It's front-loaded with the core purpose and structurally organized, though slightly dense for quick scanning.

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

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

With no output schema, the description thoroughly enumerates the returned summary block, per-advisory detail, links, and alternative versions. It also covers edge cases like timeouts, partial failures, and ecosystem scope, making it effectively complete for an agent to decide invocation.

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

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

The input schema already documents both parameters with 100% coverage, including scoped packages and default version behavior. The description adds no additional parameter semantics beyond what's already in the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly identifies a composite dependency-scanning tool for npm packages, naming deps.dev and bundlephobia as specific data sources. The verb 'scan' plus the question it answers ('should I add this npm package') leaves no ambiguity and distinguishes it from siblings.

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

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

Explicitly states when to use the tool: 'Use whenever an agent asks "is X safe / popular / small"' and provides concrete examples. It also gives an exclusion (non-NPM ecosystems) and points to an alternative (deps.dev:version directly), making the decision boundary 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 cover readOnlyHint and idempotentHint, and the description adds concrete return fields (name, summary, record_count, owner/org, url) and shows how the output connects to other tools. This goes beyond annotation-provided safety profile to explain observable 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 two sentences that pack meaningful details: the first gives purpose and domain scope, the second lists return fields and usage instructions. No redundancy or filler words, perfectly front-loaded.

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

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

For a simple search tool with no output schema, the description fully explains what is returned and how to use the result, making the tool self-contained and clearly integrated with the larger workflow. The schema examples further enrich the context.

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

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

Schema coverage is 100% with descriptive text for all three parameters (query, limit, org_id). The description references the query concept ('by keyword') but adds no additional parameter details or examples beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific action (Search) on a specific resource (City of Abbotsford GIS open geospatial datasets) with scope (by keyword). It lists example dataset categories and differentiates from sibling tools by indicating the returned URL should be passed to query_layer/layer_info.

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

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

The description provides clear usage context: search datasets, then hand the returned Feature Service URL to query_layer/layer_info for further operations. It implies the tool is the entry point for dataset discovery but does not explicitly state when not to use it or name alternative search tools.

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

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

Beyond annotations, the description discloses concrete technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. It also explains the return payload (passages with offsets and similarity scores), which is especially valuable given no output schema.

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

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

The description is information-dense yet every sentence adds value: it defines the operation, gives usage guidance, explains the pairing with a sibling, and details technical behavior. 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?

Given the tool has no output schema, the description adequately explains the return format (passages with offsets and similarity scores) and covers edge cases (truncation). It provides sufficient context for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by giving concrete examples of text ('SEC 10-K body, an article, a long tool result') and query types, while also clarifying the truncation cap. It does not add much about the limit parameter, but schema already covers it.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' which is a specific verb+resource combination. It distinguishes itself from siblings like search_datasets and ask_pipeworx by focusing on searching within already-fetched text, not broad search or Q&A.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear when-to-use guidance and an alternative approach. This directly helps the agent decide between 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 indicate non-read-only, idempotent, non-destructive, but the description goes far beyond by detailing OAuth requirements, the returned subscription id, delivery channel behaviors (email, SMS with 10/day cap, webhook with HMAC signing and auto-disable after 10 failures). This fully discloses behavioral consequences without contradicting annotations.

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

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

The description is dense but every sentence carries essential operational detail. It is front-loaded with the purpose, then prerequisites, then type-specific parameters, then delivery options. No filler or repetition; the length is justified by the tool's complexity.

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

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

Given the tool has 3 parameters (one nested), no output schema, and meaningful side effects, the description covers prerequisites, all parameter semantics, return value, delivery behavior, failure limits, and security details. It is complete enough for an agent to select and invoke correctly without additional lookup.

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 substantial semantic meaning: it explains each subscription type with concrete examples (e.g., items:["5.02"] = officer change), details the params object structure for each type, and elaborates on delivery channel parameters (verification, caps, webhook signing). This goes well beyond the schema's terse descriptions.

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

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

The description opens with a clear verb-resource statement: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and returning a subscription id.

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

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

It explicitly states the prerequisite of a Pipeworx OAuth account and excludes anonymous/BYO users, which is a when-not-to-use condition. It also mentions the always-on feed and how to pull alerts via recent_alerts, providing an alternative consumption method. It doesn't explicitly say 'use this instead of X', 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 readOnly/openWorld/idempotent, and the description adds valuable context: it returns example questions with tool+argument shapes drawn from a 'live catalog', and explains behavior with or without the topic parameter. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat long (~130 words) but is front-loaded with the core purpose and packed with useful details: example queries, output structure, usage modes, and sibling tools. Every sentence contributes value, though it could be slightly tighter.

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 meta-tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, how to invoke it, and what to expect from the output. There are no significant gaps in 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 schema fully documents the single `topic` parameter with allowed values, and the description merely repeats this with examples ('finance', 'pharma', 'betting'). Since schema coverage is 100%, the baseline of 3 is appropriate; no additional meaning is added.

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

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

The description clearly identifies this as 'the onboarding entry point' for agents, stating it returns 'category-bucketed example questions' with 'the exact tool + argument shape'. It distinguishes itself from siblings by prescribing 'Use this FIRST' before using meta-tools like ask_pipeworx, making the purpose unambiguous.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and names specific alternatives (ask_pipeworx, entity_profile, compare_entities). This provides clear, actionable guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds critical behavior beyond this: ownership enforcement ('only cancel your own subscriptions') and the non-destructive deactivation ('deactivated, not deleted') which keeps historical events accessible. This aligns perfectly with the annotations and provides richer context without contradiction.

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

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

Two concise sentences, both essential. The first states the primary function, the second clarifies ownership and non-destructive semantics. No filler or redundant 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 single-parameter mutation tool with good annotations and no output schema, the description is fully self-sufficient. It covers purpose, constraints, and side effects. There is nothing missing 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?

The schema covers the only parameter id with 100% description coverage: 'Subscription id (uuid) returned by subscribe.' The description does not add extra parameter meaning. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Cancel a subscription by id.' It also explains the ownership constraint and the deactivation behavior, which distinguishes it from subscribe and list_subscriptions among the sibling tools. 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?

The tool is clearly for canceling subscriptions, and the ownership enforcement is stated. It doesn't explicitly mention when not to use it or name alternative tools, but the context of sibling names (subscribe, list_subscriptions, recent_alerts) makes usage obvious. The mention of historical events staying available via recent_alerts hints at an alternative path for reading old data.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes well beyond them. It explains the two distinct verification routes (structured XBRL math vs. grounded pipeline), defines the special meaning of 'could_not_verify' (pipeline failure, NOT evidence), contrasts it with 'unsupported', and warns callers not to present it as a verdict. It also reveals the citation/reasoning return shape. This is rich behavioral context beyond the annotations.

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

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

The description is long but every sentence earns its place. It starts with the most recognizable trigger phrases, then states the core purpose, then dives into pipeline specifics, then gives a critical caller warning, and ends with an efficiency claim. The structure is logical and front-loaded with the most actionable info. No fluff or redundant restating of the tool name.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description is remarkably complete. It covers all main behaviors: the two verification paths, the verdict vocabulary, the meaning of each inconclusive status, the citation output, and the integration efficiency benefit. It even handles edge-case semantics (could_not_verify vs. unsupported) that a caller must know to use results correctly. There are no obvious 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%: both 'claim' and 'tolerance_pct' have thorough descriptions in the input schema, including examples and default behavior. The tool description itself does not add parameter-level details beyond what the schema provides. Per the rubric, with full schema coverage, a baseline of 3 is appropriate; the description doesn't need to compensate for missing 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 opens with natural-language trigger phrases and clearly states the tool's function: verifying factual claims against authoritative sources. It specifies a concrete verb ('verify'), a resource ('factual claim'), and distinguishes itself from siblings by calling out the two-tier pipeline (SEC EDGAR fast path vs. grounded fallback) and the fact that it replaces 4–6 sequential calls. This is far more specific than a generic 'verifies claims' statement.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives a clear when-to-use signal. It also differentiates between company-financial claims and all other factual claims, mapping each to the appropriate internal path. However, it does not explicitly name alternative tools or state when NOT to use this tool (e.g., for open-ended research), 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.