Arcgis Lubbock

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond that: it states the default model is free, notes that Anthropic calls require a BYO key and 'you pay Anthropic directly,' and describes the return structure (per-model score, confidence, signals, raw_response + combined view). 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 four sentences, each carrying distinct information: the primary function and output, default model and cost implications, return shape, and use cases. It is front-loaded and free of redundancy.

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

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

Despite having no output schema, the description explicitly states the per-model return fields and combined view. It covers when to use, parameter nuances (including the optional Anthropic key), and cost implications. For a 4-parameter tool with no output schema, this is thoroughly complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The description enriches these by naming the default model (Workers AI Llama-3.3-70b) and clarifying that _apiKey is passed straight through to Anthropic. This adds meaning beyond the schema's baseline 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 opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' This clearly states the action, scope, and key output, distinguishing it from sibling data-query tools by focusing on LLM knowledge and visibility scoring.

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

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

The description lists explicit use cases — 'AI-marketing audits, pre-launch brand checks, competitive monitoring' — and explains when to provide an API key and the default model behavior. However, it doesn't name alternative tools or explicitly state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only, non-destructive, open-world, and idempotent qualities. The description adds rich behavioral detail: it routes questions across internal tools, fills arguments automatically, returns stable citation URIs, makes one fast call, and clarifies that hallucination-resistant output is available only through another sibling. 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 longer than average but every sentence serves a purpose: routing priority, scope, examples, alternatives, and behavioral caveats. It is front-loaded with the most important instruction. The examples and repeated emphasis on 'START HERE' add minor redundancy but do not undermine clarity.

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 present, the description takes on the burden of describing what the agent will receive, and it does so clearly: structured answers with stable pipeworx:// citation URIs. It also covers scope, alternatives, examples, tier availability, and speed. Nothing essential for correct invocation 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 only describes parameters as aliases for question, providing minimal semantic value. The description compensates by explaining that the tool accepts a natural-language question, lists supported aliases, and supplies concrete examples of valid questions. This is sufficient for an agent to construct correct calls.

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 that this tool answers factual questions by routing to one of 5,724 tools across 1,497 verified sources and returning structured answers with pipeworx:// citation URIs. It also differentiates itself from siblings by positioning itself as the default entry point and naming specialized alternatives.

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

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

Usage guidance is highly explicit: 'PREFER OVER WEB SEARCH', 'Use whenever', 'START HERE for most questions', and 'Step up only when needed' with concrete conditions for using ask_pipeworx_grounded and deep_research. An agent knows exactly when to invoke this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the beta nature, the current status (no active candidate), and that it is a full working router without fallback. This provides behavioral context beyond the annotations, such as the experimental edge and comparison 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 moderately long but every sentence serves a purpose: defining what it is, stating current state, giving usage guidance, and removing the misconception of a fallback. It is front-loaded with the core identity and maintains efficient structure 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?

It covers purpose, current equivalence, usage, and clarifies it is a full router. It references the same response shape as ask_pipeworx, indirectly addressing output. Given the simple one-question input schema and strong safety annotations, it provides enough context for an agent to select and call it correctly, though it assumes familiarity with ask_pipeworx's responses.

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 description coverage is 100%: all six parameters are aliases for 'question' and each is described. The description only adds that it has the 'same arguments' as ask_pipeworx, which is generic. Since the schema already fully documents parameters, this is the baseline 3.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,724 tools, arguments, and response shape. It explicitly says it currently matches ask_pipeworx exactly and is a full working router. This distinguishes it from the stable sibling by its testing purpose, giving a specific verb+resource with clear scope.

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

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

It provides explicit when-to-use guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies it is not a fallback but a full router. While it doesn't mention alternatives for when to use the stable version, the routing-criterion 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 mark this as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: success output shape, verbatim evidence, confidence, and a full refusal_reason enum covering failure modes. It also reveals the extra LLM call cost, which is critical operational context.

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

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

The description is long but every clause earns its place: routing, behavior, output contract, refusal reasons, use cases, and cost tradeoff. It is somewhat dense and could be tightened, but nothing is 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 complex grounded-answer tool with no output schema, the description fully specifies the return contract, all failure modes, usage context, and cost consideration. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema coverage is 100% with clear alias documentation for the single required parameter. The description doesn't add parameter-specific 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 states a specific verb ('answer mode'), resource, and behavioral scope: hallucination-resistant grounded answers. It explicitly distinguishes itself from ask_pipeworx with 'Same routing as ask_pipeworx' while clarifying what makes this variant different.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' It also names the alternative and gives a preference rule: 'prefer ask_pipeworx for casual lookups.' This leaves no ambiguity about tool selection.

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

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

The description goes far beyond the annotations, detailing resolver behavior, low-confidence match handling, closed-market status, illiquid spread warnings, and resolution-rule risks like 'refund_50_50.' It also explains the internal fan-out logic and blocking behavior. This transparency greatly exceeds the baseline, especially given the readOnlyHint and idempotentHint annotations.

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

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

The description is extremely long and packed with details, including classifier lists, fan-out examples, response shapes, and safety notes. While it is well-structured with section headers, it could be trimmed for clarity. The core purpose and usage are front-loaded, but the sheer volume may overwhelm an agent. It is not as concise as it could be for a tool with only 3 parameters.

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

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

With no output schema, the description thoroughly explains what the tool returns: result.market fields, result.analysis, result.evidence, resolver contract details, parent_event extractor, news fields, and safety statuses. It also covers edge cases and resolution risks. This gives a complete picture of the tool's behavior and output.

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 describes all 3 parameters, with 100% coverage. The description adds substantial context, such as examples for the market parameter, the effect of depth ('quick = 2-3 evidence sources, thorough = full fan-out'), and the purpose of include_raw for keeping responses under ~20KB. This enriches understanding beyond the schema.

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

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

The description clearly states what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input type (slug, URL, or question text) and the output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_arbitrage or validate_claim, which have different objectives.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear guidance on when to use the tool. It does not explicitly mention when NOT to use it or name alternative tools, but the context is sufficient.

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

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

Annotations declare readOnlyHint and non-destructive, so the description adds rich behavioral detail: data sources (SEC EDGAR/XBRL, FAERS), specific metrics per type, sorting by primary metric, and return format with citation URIs. This goes far 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 dense but every sentence earns its place: trigger phrases, preference rule, data specifics, sorting behavior, return format, and replacement count. 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?

With no output schema, the description explains return values ('paired data + citation URIs'). It covers both entity types, sorting, fiscal year handling, and the efficiency gain, making it complete for invocation.

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

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

Schema coverage is 100%, but the description adds significant meaning by explaining what each type retrieves (financial metrics vs FAERS/FDA/trial counts) and gives examples of valid values. This helps the agent select appropriate parameters.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' – a specific verb+resource. It lists trigger phrases and contrasts with sequential lookups, distinguishing it from siblings like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides clear trigger examples. It also differentiates company vs drug use cases, giving strong when-to-use context.

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

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

The annotations already establish readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial context beyond them: account and paid-plan requirements, expected latency, parallel decomposition, findings packet contents, gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, and citation_uri resolvability. This is unusually transparent behavior disclosure.

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

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

The description is long, but every sentence carries operational value: auth constraints, sibling routing, source scope, output structure, depth semantics, latency, and caveats about open-web content. It is front-loaded with the critical account requirement and fallback tool, and contains 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?

Given the tool's complexity, absence of an output schema, and rich sibling set, the description is remarkably complete. It covers required authentication, pricing, expected output shape, timing, source scope, multi-hop behavior, and failure semantics, leaving an agent with enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description nevertheless adds meaning by explaining that question accepts broad natural-language multi-part queries, and that depth controls facet count and follow-up hops — beyond what the enum names alone communicate.

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 names a specific verb and resource: it performs grounded multi-source research across Pipeworx's 1,497 structured data sources, decomposes questions into facets, and routes them to 5,724 tools in parallel. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, making its purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use it for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, use ask_pipeworx for breaking/colloquial current news, and use ask_pipeworx if not signed in. It also explains depth-level tradeoffs, so an agent can select it correctly against sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: returns top-N tools with names, descriptions, full input schemas with curated examples, and that each result is ready to call directly without a second schema lookup. This goes beyond annotations by describing the return payload and convenience 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 front-loaded with a clear verb+resource statement, then provides a helpful but somewhat long list of domains, followed by return format and usage guidance. The domain list is verbose but serves to clarify scope. It's concise overall—three sentences with no filler—but the long list prevents a 5.

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

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

With no output schema, the description adequately explains return values: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also covers when to use it. Given the tool's meta-purpose and rich annotations, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema fully documents all 6 parameters. The description reinforces the query concept ('describing the data or task') and mentions 'top-N' which relates to the limit parameter, but adds no new semantic information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explicitly distinguishes itself from siblings by positioning as the discovery tool to call first. The phrase 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)' differentiates it from 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 when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies when not to use it (when you need a single answer), providing clear context 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: it fans out across multiple sources in parallel, returns specific fields (cik, recent_filings, fundamentals, patents, news, LEI), sorts fundamentals by period_end descending, soft-fails on the USPTO API sunset, and uses a GDELT→GNews fallback. No contradiction with annotations is present.

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

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

The description is dense and front-loaded with examples, but every section contributes to understanding the tool's scope, return values, and constraints. It is longer than average, yet the complexity of the multi-source fan-out justifies the length. The structure flows from usage triggers to return details to input constraints, making it easy to scan.

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

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

With no output schema, the description takes on the burden of explaining return values. It covers all major return categories (cik, recent_filings, fundamentals, patents, news, LEI), provides URI formats, fallback behavior, and sorting order. For a tool with this complexity, the description is remarkably complete, leaving few gaps for the agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the parameter formats with concrete examples ('AAPL', '0000320193') and explicitly reiterates that names are not supported, providing actionable guidance alongside the schema's own descriptions. While it doesn't add entirely new semantics, the examples and usage hints elevate it slightly.

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

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

The description opens with multiple natural-language triggers ('Tell me about X', 'research Acme') and explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from siblings by advising ALWAYS PREFER over chaining single-pack lookups for holistic views, making the tool's purpose unmistakable.

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

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

The description explicitly states when to use the tool (when the user asks for a holistic view) and contradicts chaining single-pack SEC/XBRL/news lookups. It also provides an alternative path: if only a name is given, use resolve_entity first. This gives clear contextual guidance and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds value by explaining the purpose ('previously stored memory') and the rationale for deletion (stale, done, sensitive data). 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 just two sentences, front-loaded with the primary action, followed by usage guidance. Every word earns its place with no filler.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description fully covers purpose, usage, and context. It is complete and actionable.

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 describes 'key' as 'Memory key to delete' with 100% coverage. The description repeats 'by key' but adds no new details about formats, defaults, or edge cases. Baseline 3 applies as schema does the heavy lifting.

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

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

The description clearly states the tool's function with a specific verb ('Delete') and resource ('a previously stored memory by key'), which immediately distinguishes it from sibling tools like 'remember' and 'recall'.

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 use cases are provided ('context is stale, the task is done, or you want to clear sensitive data'), and the description suggests pairing with 'remember' and 'recall' as related tools. It does not explicitly say when not to use, but the guidance is clear and practical.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the process: it fetches the page, extracts key data, and emits a standard markdown blob. This clarifies what 'generate' actually entails and the output format, going 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 three sentences: core function, process summary, and use cases. It is front-loaded with the primary action, every sentence adds value, and there is no redundant fluff.

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

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

Given the tool's simplicity (2 params, 1 required) and the absence of an output schema, the description covers what the tool does, how it works, and what the output looks like (a single text blob for site-root/llms.txt). Combined with annotations for safety, this is complete.

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

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

Schema description coverage is 100%, so both 'url' and 'max_links' are fully documented. The description doesn't add extra parameter semantics but reinforces that the URL can be any site or landing page. This meets the baseline for high schema coverage without adding significant new information.

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: generate an llms.txt file for any URL, with a specific process (fetch, extract title/description/key links, emit standard markdown). It distinguishes itself from sibling tools by focusing on creating the file rather than analyzing visibility or 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 three use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing how an AI crawler sees a competitor. While it doesn't name alternative tools, the context is clear enough to know when to invoke 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 read-only, idempotent, non-destructive behavior, and the description adds detail about what is returned (fields, geometry type, record count, capabilities). However, it does not disclose any additional behavioral traits such as network dependence, potential latency, or error conditions. The description adds some value but does not go beyond the safety profile already covered by annotations.

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

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

The description is a single, compact sentence that front-loads the verb and resource, then enumerates the specific outputs. No filler words or redundancy, every part contributes to understanding.

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

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

Given the tool's simplicity (one parameter), strong annotations, and a description that lists all key return components, the description is complete for an agent to understand what the tool does and when to use it. No output schema exists, but the description compensates by naming the schema fields, geometry type, record count, and capabilities.

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 only one parameter (url) with a clear description and example, covering 100% of parameter semantics. The tool description merely restates 'by url' without adding any new meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('an ArcGIS Feature/Map Service layer's schema by url') with explicit output components (fields, geometry type, total record count, capabilities). This distinguishes it well from sibling tools like query_layer, which would be for data retrieval rather than schema introspection.

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 makes the tool's purpose clear—obtaining schema metadata for an ArcGIS layer—which implicitly guides when to use it (before querying or using layer data). It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear due to the tool's focused scope.

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, but the description goes further by disclosing the default behavior (only active subscriptions) and the effect of include_inactive. It also lists the returned fields, which is critical since no output schema is provided. No contradiction with annotations exists.

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 action and scope. The first sentence states the purpose and return values, the second provides usage guidance. No wasted words or redundant repetition of schema or annotations.

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 list tool with one optional parameter and no output schema, the description covers all essential aspects: scope (caller's subscriptions), return shape, and practical use cases. The inclusion of parameter behavior (default active only) is also covered in conjunction with 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?

Schema coverage is 100%, so the include_inactive parameter is fully documented in the input schema. The description does not add new parameter-specific semantics beyond the schema; it only references 'active' in passing. This meets the baseline for high schema coverage 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 begins with a specific verb 'List' and identifies the resource as 'the caller's active subscriptions', clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the exact return fields, making the tool's output 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 the tool: 'review what you're monitoring before adding more' and 'find an id to cancel'. This provides clear context for use and implies it is a prerequisite for subscribe/unsubscribe actions, which are listed among sibling tools.

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

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

Annotations are sparse (all false), but the description adds rich behavioral context: claim_token workflow, rate limit (5 per identifier per day), free and not counted against quota, daily digest reading, and roadmap impact. It also explains what happens without an account, going beyond the structured annotations.

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

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

The description is longer than average but every sentence contributes unique value: purpose, use cases, exclusions, token mechanics, rate limits, cost. No fluff or repetition; it builds logically from what the tool does to how to use it.

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 still explains the return concept (claim_token for anonymous filings). It covers prerequisites (none), special cases (claim_token-only invocation), limitations (rate limit), and operational details. The tool's full behavior is documented without leaving major gaps.

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

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

Schema description coverage is 100% and includes detailed descriptions for all parameters. The description enhances this by illustrating the claim_token usage (`pipeworx_feedback({claim_token:"pwfb_…"})`) and emphasizing that filing is possible without an account. It also reinforces the type enum meanings, adding a bit beyond the schema's own descriptions.

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

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

The description states a specific purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates use cases (bug, feature, data_gap, praise), and its resource (Pipeworx tools) is clear. This distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use instructions: bugs, missing features, data gaps, and praise. It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for non-Pipeworx tools. Includes handling for uncertainty ('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?

With readOnlyHint and idempotentHint already true, the description adds valuable context: it explains the data source (CF analytics-engine), states no PII is involved, describes the output structure as '(pack, tool, count)', and discloses caching behavior (5min-1h). This goes beyond the annotations and provides 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 three sentences, front-loaded with the main purpose, followed by concrete use cases and technical details. Every sentence adds value, and the structure is easy to scan.

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 explains what is returned (top tools, top packs, total call volume) and the data shape ('(pack, tool, count)'). It also covers caching and data provenance. For a simple read-only tool with one optional parameter, this is complete.

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

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

The schema already covers the single parameter 'window' with a description that includes defaults and semantics (shorter vs longer windows). The tool description merely mentions the window options without adding new meaning, 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 what the tool does: returns top tools, top packs, and total call volume for what other AI agents are calling on Pipeworx. It uses specific verbs ('returns') and names the resource ('Pipeworx trending'), and the phrasing distinguishes it from siblings like discover_tools by focusing on current agent 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 explicit 'Useful for' use cases: discovering hot data sources, confirming canonical tools, and checking use-case alignment. These are clear when-to-use contexts, but it does not explicitly mention when not to use or name alternative tools, so it falls short of the full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: partition filter behavior, semantic similarity threshold (≥0.30 Jaccard), fill check against live CLOB depth, and the exact condition under which a signal should not be traded (realizable_edge_pp ≤ 0). This goes far beyond what annotations provide and creates no contradictions.

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

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

The description is long, but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds value, though some details (e.g., exact response fields) are densely packed. Slightly verbose, but the structure keeps it scannable.

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

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

For a tool with no output schema, the description covers purpose, all three modes, response shape, edge cases, and related tools. It even explains the fill-check behavior and how to interpret edge values. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for both parameters, but the description enriches meaning significantly. For event, it clarifies it walks child markets and checks date/threshold-axis ordering plus partition sum; for topic, it explains cross-event search and flattening. It also documents the no-arg default. This is high-value semantic context beyond the schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and differentiates from siblings like polymarket_fill_risk, which is referenced for custom sizing. This is a textbook example of purpose 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 explicitly instructs when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. It also recommends event for specific markets, explains cross-event mode's advantage over single-event, and points to polymarket_fill_risk for custom sizing. This exceeds mere context by providing exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: caching at KV level with 1h TTL keyed on knobs, excluded Fed bets with reasoning, a 24h-move warning when recent price changes exceed the edge, and detailed diagnostics to explain empty segments. It also explains that edge is net of slippage and that Kelly fractions are capped at 0.25, going 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 extremely information-dense, organized into clear sections: purpose, model families, response structure, knobs, and caching. It front-loads the core purpose in the first sentence and every sentence adds necessary detail for a complex tool with no output schema. The use of capitalization and colons makes it scannable without sacrificing completeness.

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 (9 parameters, no output schema, multi-segment responses), the description is remarkably complete. It explains the three model families, response top-level structure (by_segment, fed_candidates, _diagnostics), why segments might be empty, and the caching behavior. It even covers exclusion of Fed bets due to unreliable signals. The presence of diagnostics addresses the common agent frustration of empty results with no explanation. This is exceptionally thorough.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds value by grouping parameters under 'TRADEABLE-EDGE KNOBS' and explaining their collective purpose (e.g., min_liquidity/max_spread_pp drop opportunities where edge isn't realizable, min_partition_leg_kelly overrides min_kelly for partitions). This helps the agent understand how to reason about the knobs together, slightly elevating above baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage (which focuses on arbitrage between markets) and polymarket_edge_tracker (which tracks edges over time). The stated use case is targeted and actionable.

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

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

Provides a clear use case: 'Built for "what should I bet on today"' and explains that agents avoid paging hundreds of markets. It also describes the tuning knobs (min_liquidity, max_spread_pp) and caching behavior. However, it does not explicitly name alternative tools or state when NOT to use this tool (e.g., if you need historical edge tracking), leaving a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description goes far beyond that, illuminating response semantics (tracked/expired/snapshot_dates), the meaning of trend and decay_pp_per_day (signed by trade direction), the 60-day TTL and snapshot-gap behavior, and the daily-closes vs. intraday limitation. This is exemplary behavioral disclosure.

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 organized into clear segments: core purpose, args, response fields, and limits. Each sentence adds substantive detail, and the front-loaded question makes the tool's purpose immediately graspable. Despite its length, it is efficient for the complexity it covers.

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

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

With no output schema, the description thoroughly explains return values: tracked/expired/snapshot_dates and their semantics. It also covers time bounds (TTL, snapshot start), data gaps, and computation nuances. For a moderately complex tool with two optional params, this is fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the defaults (days=14, window=1wk) and adds 'max 30' and 'snapshot family' phrasing, but these are already present in the schema. It does not add new meaning beyond what the schema's parameter descriptions already convey.

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, technical statement: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and frames the core question 'how long has this edge existed and is it shrinking?' This clearly differentiates it from raw edge tools like polymarket_edges and arbitrage tools, and it immediately explains the tool's unique value.

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 clearly implies when to use this tool (whenever edge longevity or decay matters) and contrasts fresh vs. old edges to illustrate relevance. It does not explicitly name alternatives among the sibling tools, but its phrasing 'built from daily polymarket_edges snapshots' implies the raw alternative. This is strong guidance but lacks an explicit 'use X for raw edges' exclusion.

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

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

Annotations declare read-only and non-destructive, and the description adds behavior beyond that: it 'walks the ladder', interprets size_usd differently per mode, and discloses the risk of partial basket fills converting arbs into unhedged directional positions. It also lists return fields, giving the agent an accurate model of tool behavior. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It is structured with clear sections (SINGLE-MARKET, BASKET) and enumerates return values and defaults. Despite the length, it is dense and information-dense with no fluff, making it an effective reference for a complex 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 (two modes, multiple return fields, risk warnings), the description is thorough. There is no output schema, so the description carries the full burden of conveying return values and semantics, and it does so comprehensively, covering edge cases like thin legs and forced directional risk. It also addresses when to use it relative to alternatives.

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

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

Although schema description coverage is 100%, the description adds significant meaning: it explains the 'one of market or event' requirement, side defaults and how size_usd is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional shares per leg). These semantics are not in the schema and are critical for correct invocation.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and slippage. The two modes (single-market and basket) are explicitly defined, leaving no ambiguity about what the tool does.

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

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

The description states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the distinction between single-market and basket modes and why partial fills are dangerous, effectively contrasting with alternatives and giving clear context for selection.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing matching heuristics, compatibility codes, skipped/unclassified legs, the fees omission, and gross-vs-net spread interpretation. It also warns that returned pairs can carry non-empty warnings even when matches exist, which is exactly the kind of behavior an agent needs to know.

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

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

The description is front-loaded with the core purpose and mode selection, then organized into safety fields, codes, counters, and caveats. It is long and repeats a few details (e.g., temporal alignment codes appear twice), but the density is largely justified by the number of edge cases an agent must handle.

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

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

With no output schema, the description must explain return values and trust boundaries itself. It does this thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment, fees_note, skipped counters, and the unclassified-leg behavior are all covered, so an agent can safely 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?

The schema already covers all three parameters with descriptions and examples, so the baseline is met. The description adds meaning by explaining the mode relationship — `topic` auto-fetches a matching event, explicit ticker/slug overrides the mapped side, and both modes run the identical matcher — which the schema alone does not convey.

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 purpose: compute the cross-venue spread between Kalshi and Polymarket for the same resolving question, in two explicit modes. It is clearly distinguishable from sibling Polymarket tools, which focus on single-venue edges or arbitrage rather than 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?

Provides clear usage context: two invocation modes (pre-mapped `topic` vs explicit ticker/slug), plus behavioral caveats like 'pre-mapped ≠ tradeable' and the fact that both compatibility fields must be read. It does not explicitly name sibling alternatives or state when-not-to-use, so it falls short of the full comparative 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=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds the return format (attribute rows and geometry) and query characteristics (SQL-like where, sampling pattern), which goes beyond the annotations and helps the agent predict 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?

Two sentences, front-loaded with the core purpose, including key parameters and a usage tip. Every word earns its place, and the backticked parameter names improve readability.

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

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

Given no output schema, the description explains that it returns attribute rows and geometry, which is essential. It also ties into the search_datasets workflow and gives a sampling pattern. It does not cover edge cases (e.g., pagination limits) but the schema covers those, and the tool is relatively simple.

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

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

The input schema already has 100% coverage with descriptions for all six parameters, so the baseline is 3. The description summarizes parameter types (SQL-like where, comma-separated out_fields) but does not add significant meaning beyond the schema. The examples in the schema are more informative than the description text.

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 queries an ArcGIS Feature/Map Service layer by URL, using a specific verb and resource. It also mentions the URL comes from search_datasets, which distinguishes it from sibling tools like layer_info or search_within.

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

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

It gives a clear context: use with a URL from search_datasets, and provides a concrete sampling pattern (where="1=1" + out_fields="*"). However, it doesn't explicitly exclude alternatives or state when not to use it, though the reference to search_datasets implies a workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds useful context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the optional key behavior for listing. This goes beyond what annotations provide without contradicting them.

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

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

The description is three sentences, each serving a distinct purpose: action, use case, and scoping/relations. There is no redundant fluff, and the most critical information (retrieve/list) is front-loaded in the first sentence.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers the essentials: functionality, use case, and identifier scoping. It could mention the return value format or behavior for missing keys, but these are minor gaps given the tool's simplicity and the presence of annotations.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to retrieve (omit to list all keys)'. The description adds real-world examples of what keys might contain ('target ticker, an address, prior research notes') and reinforces the omit-to-list behavior, enriching the schema's basic description.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb+resource ('Retrieve a value previously saved via remember, or list all saved keys'). It distinguishes itself from siblings by explicitly pairing with remember and forget, making its role in the memory toolset unambiguous.

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

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

The description gives explicit use cases ('look up context the agent stored earlier — the user's target ticker, an address, prior research notes') and mentions complementary tools (remember, forget). However, it lacks explicit 'when not to use' guidance beyond implying not to re-derive information from scratch.

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 a behavioral trait that contradicts the provided annotations: it says 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which is a state mutation, while the annotations declare readOnlyHint: true. This gives conflicting safety signals to the agent.

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

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

The description is four sentences, front-loaded with the main verb and resource. Each sentence serves a purpose: return contents, filtering, mark_read behavior, and an alternative access method. It is appropriately sized without fluff.

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

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

The description covers the return payload (source, citation_uri, raw event payload), filtering, mark_read semantics, and the REST alternative. Since there is no output schema, it usefully outlines the returned fields. It could mention limit/unread_only but those are well-defined in the schema, so overall completeness is high.

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

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

Schema description coverage is 100%, and the description adds meaningful semantics beyond the schema: gives a concrete type example ('sec_8k'), clarifies the ISO format for 'since', and explains the side-effect of mark_read. Limit and unread_only are self-explanatory from the schema, so the added value earns 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 clearly states the tool's purpose: 'Pull fired events from your subscription feed' and 'Returns the most recent alerts'. It uses a specific verb and resource, and distinguishes itself from siblings like list_subscriptions by focusing on the alert feed contents.

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: filtering by type and/or since, setting mark_read for read-state management, and noting that polling works. It also mentions an alternative REST endpoint for scripts/dashboards, which serves as an explicit alternative. It doesn't explicitly state when not to use the tool, but the 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?

While annotations already declare readOnly/idempotent/destructive safety, the description adds substantial behavioral detail: fan-out to multiple sources, the GDELT→GNews fallback on rate-limit/5xx, and a soft-fail for USPTO due to the PatentsView API sunset. It also discloses that it returns grouped changes with citation URIs and executes in one parallel call.

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 contributes: opening intent examples, source enumeration with fallback/soft-fail details, parameter formats, return structure, and an alternative tool pointer. It is front-loaded with use cases, and no word is wasted.

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 (3 params, no output schema, multiple sources), the description covers the core invocation surface well: what sources are queried, what `since` accepts, what is returned (changes[] grouped by source + total_changes + citation URIs), and when to use an alternative. It lacks explicit detail on error behavior or empty results, but the provided guidance is sufficient for typical 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?

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by elaborating `since` formats with concrete examples ('7d', '30d', '3m', '1y'), recommending '30d'/'1m' for typical monitoring, and clarifying how `value` (ticker or CIK) is used across the different data sources. This extra guidance 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 clearly identifies the tool as a change feed for a company over a recent window, with concrete intent examples ('What's new with X') and explicit sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from the sibling entity_profile tool by contrasting dynamic changes vs. static profile.

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

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

The description provides explicit usage guidance, including example queries that indicate when to use the tool and a direct recommendation: 'Use entity_profile instead when you want the static profile... regardless of window.' It also gives practical advice for the `since` parameter ('Use "30d" or "1m" for typical monitoring').

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 annotation already declares non-readonly and non-destructive behavior, and the description goes further by explaining the key-value store is scoped by user identifier and noting persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). This adds meaningful lifecycle context beyond the annotations. No contradiction with annotations.

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

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

Three sentences, each with a distinct job: statement of purpose, usage guidance, and storage/behavior details. It is front-loaded and avoids 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 2-parameter write tool with annotations, the description covers purpose, usage, storage semantics, persistence, and complementary tools. There is no output schema, but return values are not essential to understanding this tool.

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

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

With 100% schema coverage, the description rests on solid schema descriptions. It reinforces the key-value pair concept and gives examples ('subject_property', 'target_ticker') that align with the two parameters, but adds little technical detail beyond the schema. This meets the baseline for covered schemas.

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

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

The description opens with a specific action ('Save data') and a clear resource ('data the agent will need to reuse later'), then distinguishes itself from siblings by explicitly naming recall (retrieve) and forget (delete) as complementary operations. This makes the tool's role in the memory lifecycle unmistakable.

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

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

It explicitly states when to use it ('Use when you discover something worth carrying forward') and gives concrete examples (resolved ticker, target address, user preference). It also points to alternatives ('Pair with recall to retrieve later, forget to delete'), satisfying the 'when/alternatives' criterion.

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 surfaces important behaviors: enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, ambiguous matches return figi_candidates instead of asserting, unresolved identifiers are explicitly listed under `unresolved`, and each call cascades through multiple lookup endpoints. This is exactly the kind of behavioral context annotations cannot convey.

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

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

The description is long and dense, with many parentheticals, but it is front-loaded with user-intent examples and every sentence conveys a distinct fact needed for correct usage. Some redundancy exists, such as repeating the 'never the question's full noun phrase' point in the parameter description, but overall the length is justified by the tool's multi-source complexity.

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

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

With no output schema, the description carries the full burden of explaining what the agent should expect back. It covers resolution targets, source provenance labeling, ambiguous-name behavior, unresolved-identifier behavior, supported entity types, input formats, fallback degradation, and the fact that each call replaces multiple manual lookups. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Although the schema already covers both parameters at 100%, the description adds substantial meaning: accepted input formats for company (ticker, CIK, ISIN, name), drug brand/generic examples, and a critical negative example for bonds telling the agent to pass the issuer exactly as printed and never the full noun phrase. This materially improves invocation accuracy.

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

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

The description opens with concrete query examples and then states a precise job: resolve a user-spoken NAME to canonical/official identifiers other tools require as input. This clearly differentiates it from sibling tools like entity_profile and compare_entities, which are about profiling or comparing entities rather than converting names to IDs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a strong, actionable usage rule. It does not, however, name the alternative tools or state when NOT to use resolve_entity (e.g., when you need a profile rather than an identifier), so it stops short of full exclusion 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 readOnly, openWorld, idempotent, and non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with confidence and signal density. No contradictions; it complements the annotations with useful operational context.

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

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

The description is exactly two sentences, front-loaded with the main action, and every sentence adds value. It states the core function, the method (probes with ai_visibility_check), the output, and a concrete use-case example. No redundancy or filler.

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

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

No output schema exists, but the description explicitly names the return fields ('ranked list with score, confidence, signal density per entity'), which directly addresses what the agent will get. The complexity is moderate (4 parameters, 1 required), and the description covers the workflow and purpose sufficiently for an agent to decide when to use it.

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

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

Schema description coverage is 100%, and each parameter (models, _apiKey, context, entities) already has a clear description. The tool description adds only the narrative that the first entity is the 'subject' and others are competitors, which is a slight enhancement over the schema's 'First entry treated as the subject...' but not substantial beyond that. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It names the specific verb ('Compare'), the resource (AI visibility across entities), and distinguishes from siblings by mentioning it probes with ai_visibility_check and ranks results. The example query clarifies its use case.

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

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

The description provides a clear context: 'Useful for competitive AI-marketing audits' and gives an example question. It does not explicitly mention when not to use it or name alternatives, but the contrast with the single-entity sibling ai_visibility_check is implied through the phrase 'across multiple entities.'

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

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

Beyond the readOnly/idempotent hints, the description discloses important behavioral traits: partial failures degrade gracefully, the first bundlephobia measurement can take 5-30s, and sources_failed will list timeouts while the rest of the results still return. This gives the agent essential expectations about latency and partial results.

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 core purpose, followed by usage guidance, return structure, ecosystem scope, and failure behavior. Every sentence earns its place; no filler or repetition.

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

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

With no output schema, the description thoroughly explains the return format (summary block fields, per-advisory details, links, alternative versions). It also covers ecosystem limitations and timeout behavior, making the tool's behavior fully predictable for an agent.

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

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

The schema already provides 100% coverage of both parameters (package and version) with clear descriptions, so the description doesn't need to repeat them. The description adds no extra parameter-specific semantics beyond what the schema offers, which is acceptable given the 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 it is a composite check for 'should I add this npm package to my project' and specifies the exact data sources (deps.dev and bundlephobia) and what they measure (license, advisories, bundle size, etc.). This distinguishes it from sibling tools like validate_claim or scan_competitor_ai_presence, which serve different functions.

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

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

It explicitly says 'Use whenever an agent asks...' and gives concrete examples like 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides an alternative for non-NPM ecosystems (deps.dev directly), making the when-to-use and when-not-to-use guidance 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/non-destructive. The description adds concrete return-value details (name, summary, record_count, owner/org, URL) and an explicit integration pattern with sibling tools, which provides transparency about what to expect beyond the structured fields. No contradictions with annotations.

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

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

The description is exactly two sentences: the first delivers the core purpose and scope, the second covers output and downstream usage. Every word is informative, no redundancy or filler.

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

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

With no output schema, the description compensates by listing the return fields and providing integration guidance. Combined with strong annotations and full schema descriptions, it is largely complete for a search tool. Minor gaps remain (e.g., sort order, matching behavior), but these are not critical for invocation.

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

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

The input schema covers 100% of parameters with clear descriptions for query, limit, and org_id. The tool description mentions 'by keyword' which aligns with the query parameter but adds no additional parameter-level meaning. The baseline of 3 applies since schema description coverage is high.

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 verb (Search), resource (City of Lubbock GIS open geospatial datasets), and scope (parcels, zoning, public works & city services). It explicitly distinguishes itself from sibling tools by naming query_layer/layer_info as the next step after receiving the URL, clarifying its role as a discovery tool.

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

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

The description provides a clear usage context: use to find datasets, then pass the returned URL to query_layer/layer_info for further data access. It implies the tool is the entry point for exploring available geospatial data, though it does not explicitly mention when to avoid it or compare it to alternatives like search_within.

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 annotation hints (read-only, open-world, idempotent), the description discloses technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char truncation cap with a flag, and return of offsets for quote verification. These non-obvious details are valuable for an agent deciding to use the tool.

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

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

The description is three sentences, each serving a distinct purpose: core function/usage, pairing with another tool, and technical constraints. It is front-loaded with the primary action and avoids redundancy or fluff.

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

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

With no output schema, the description takes responsibility for explaining return values, and it does say 'top-N passages with character offsets and similarity scores' and mentions a truncation flag. However, it does not specify the exact output structure (e.g., field names), so the agent would need to infer the precise response format; this small gap prevents a 5.

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 describes all three parameters with clear explanations (100% coverage), so the baseline is 3. The description adds contextual flavor (e.g., text is an already-pulled record) but does not materially extend the parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool performs semantic search inside a provided text, returning top-N passages with character offsets and similarity scores. It is explicitly contrasted with siblings like ask_pipeworx_grounded, making the tool's specific role unmistakable.

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

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

The description provides explicit guidance: 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded for a grounded-answer workflow. This gives clear context and an alternative, fulfilling the when-to-use and when-not-to-use requirement.

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?

Annotation Contradiction: The annotations declare idempotentHint=true, but the description says 'Create a proactive monitoring subscription' and 'Returns the new subscription id,' implying a new resource is created each time. This contradicts the idempotency hint. Additionally, the main description omits the webhook delivery channel, which is only described in the input schema, and does not clarify idempotent behavior or failure states.

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

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

The description is dense but efficient; each sentence provides meaningful details about purpose, requirements, types, and delivery. It could be slightly more concise, but the structure is logical and front-loaded with the core function.

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

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

For a complex tool with 3 params, nested objects, and multiple delivery channels, the description covers most key aspects: purpose, auth requirements, subscription types, delivery options, verification, and return value. It omits webhook support and two types from the main description, but the rich input schema fills those gaps. The idempotency conflict is a notable weakness.

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% parameter description coverage, and the description adds valuable examples (e.g., items:["5.02"] for sec_8k, topic:"fed" for polymarket_edge, series_id:"UNRATE" for fred_series). It also explains delivery channel constraints (SMS verification, 10/day cap) that go 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 states the tool creates a proactive monitoring subscription to a live-data event stream. It names specific subscription types and delivery channels, which distinguishes it from sibling tools like unsubscribe, list_subscriptions, and recent_alerts.

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: when to monitor an event stream, with examples for each supported type. It also contrasts with pulling alerts via recent_alerts or the registry endpoint. However, it does not explicitly mention exclusions or when to prefer alternative tools like validate_claim or deep_research.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond annotations by explaining the exact return format (category-bucketed example questions with tool+argument shapes), the live catalog source, and the behavior with and without the topic parameter. 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 but well-structured: it opens with example phrasings, states the tool's purpose, lists return categories, explains usage variants, and closes with explicit when-to-use guidance. Every sentence contributes meaningful information 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?

With no output schema, the description sufficiently explains the return value (category-bucketed example questions with tool+argument shapes). It also places the tool in context relative to meta-tools and sibling tools, covering prerequisites, usage, and expected content. The description is complete for an onboarding tool of this complexity.

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

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

Schema coverage is 100% for the single optional parameter. The description adds extra value by providing concrete examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter returns the full spread, which goes beyond the schema description.

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

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

The description clearly states the tool's purpose: it is an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like discover_tools by specifying the unique output (example questions with tool+argument) and its use as a first step for learning meta-tools.

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

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

Explicitly tells the agent when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides guidance on the optional topic parameter and the no-argument default behavior, covering alternatives without ambiguity.

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

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

The description adds significant behavioral detail beyond the annotations: it discloses ownership enforcement ('you can only cancel your own subscriptions'), explains that the row is deactivated rather than deleted, and clarifies that historical events stay accessible. This aligns with and enriches the destructiveHint=false and idempotentHint=true 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 that front-load the core action ('Cancel a subscription by id') and then add essential caveats about ownership and deactivation. There is no filler; every sentence contributes meaningful information.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, ownership constraint, and the persistence of historical data via recent_alerts. It stops short of describing specific error responses when ownership fails, but the tool's simplicity and the clarity of the effect make this a minor gap.

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

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

Schema coverage is 100% and the parameter 'id' is already well-described as 'Subscription id (uuid) returned by subscribe.' The description repeats 'by id' without adding further semantics, so it does not exceed the baseline expected given the high schema coverage.

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

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

The description uses the specific verb 'Cancel' and identifies the resource 'a subscription by id,' clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions.' It is a specific and unambiguous statement of what the tool does.

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

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

The description implies when to use the tool (to cancel a subscription) and contrasts with 'subscribe' by context. It also notes that historical events remain available via recent_alerts, providing useful post-condition context. It does not explicitly state when not to use it, but the intended use case 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description explains the sophisticated behavior: the SEC EDGAR + XBRL fast path vs grounded pipeline, the meaning of each verdict, the critical distinction between could_not_verify (check did not happen) and unsupported (no source), and the return format with citations. This is exactly the kind of behavioral context that helps an agent interpret results safely.

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, front-loaded with trigger phrases and a clear 'when to use' statement. Each sentence carries meaningful info, from routing logic to verdict definitions to the important error-handling caveat. It could be trimmed slightly, but the structure is logical and scannable.

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

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

Despite having no output schema, the description enumerates all possible verdicts and their meanings, explains the return payload (value with citation and reasoning), and covers error conditions. It also explains the two-routing paths. This is a complete description for a tool of this complexity, especially with rich annotations.

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

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

The input schema fully documents both parameters with descriptions (100% coverage). The description adds some context about tolerance ('exact percent-delta math' and default cap at 5) but does not substantially enhance parameter understanding beyond the schema. Thus 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 immediately identifies the tool as 'natural-language claim verification against authoritative sources' with trigger phrases like 'is it true that…' and 'fact check', clearly distinguishing it from generic Q&A tools. It specifies two pathways (structured SEC for company-financial claims, grounded pipeline for all else) and the returned verdict types, 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and describes the routing behavior, but it does not explicitly name alternative tools or state when not to use this tool. The 'Replaces 4–6 sequential calls' note implies efficiency but not an exclusion, so the guidance is clear but not fully exhaustive.

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