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 declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond these: it returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes 'one fast call'. This enriches the agent's understanding of what to expect.

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

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

The description is fairly long but information-dense. It's front-loaded with 'PREFER OVER WEB SEARCH' and organized into use cases, examples, and escalation paths. Minor redundancy exists (e.g., 'START HERE' and 'works on every tier' could be condensed), but every section earns its place.

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

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

Given no output schema and high complexity, the description covers return behavior (citations), scope (verified sources, domains), performance ('one fast call'), and alternatives. It fully equips the agent to decide when to invoke this tool and what output to expect.

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

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

Schema coverage is 100% with descriptions for the question parameter and its aliases. The description enhances semantics by providing concrete example questions and phrasing patterns ('what is', 'look up', 'current'), helping the agent formulate effective queries. This exceeds the baseline for full 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 identifies ask_pipeworx as a routing tool for factual questions, with a specific verb ('routes', 'returns') and resource (5,521 tools across 1,452 sources). It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making the unique role obvious.

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

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

Explicit when-to-use guidance is given: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions'. It also names alternatives for specific cases (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), providing clear context 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?

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and no destructive hint, the description adds valuable context: candidate routing improvements are enabled live only when under test, no candidate is currently active, and it 'Falls back to nothing — this IS a full working router.' This prevents misconceptions about beta reliability and clearly explains current 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 the core purpose and uses four sentences, each carrying important information: beta status, current candidate state, usage instruction, and operational assurance. Despite its length, every sentence earns its place, and the formatting makes the experimental nature clear.

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 beta router tool with dynamic candidate behavior, the description covers what it is, what it does now, when to use it, how results are used, and how it relates to the stable version. Since it states the response shape is identical to ask_pipeworx, no output schema is needed, and the tool is fully contextualized 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?

Schema description coverage is 100%, with all six parameters clearly documented in the schema, including aliases for 'question.' The description only repeats that arguments are the same as ask_pipeworx and adds no meaningful parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,521 tools and same response shape, and distinguishes it from the stable ask_pipeworx sibling. It states the specific function: 'Use it exactly like ask_pipeworx when you want the newest routing.'

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 when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable alternative (ask_pipeworx) and explains the comparison mechanism. However, it does not explicitly say when not to use it, beyond calling it the 'experimental edge.'

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the extra LLM call cost, the explicit refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), and that it strictly uses only the tool result. It also describes the return structure including evidence and confidence. No contradiction with annotations.

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

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

The description is dense and front-loaded with the key phrase 'Hallucination-resistant answer mode.' While it is lengthy (two long sentences), every part adds value: routing, extraction, return format, usage cases, and cost trade-off. It is concise relative to the complexity of the 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?

With no output schema, the description fully compensates by specifying the exact return object and refusal reasons. It covers the tool's behavior, cost, and when to use it. This is complete for a tool of this complexity, leaving no significant gaps for an agent to misinterpret.

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

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

The input schema has 100% description coverage, with all parameters described as aliases for 'question.' The description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate for a case where the schema handles parameter documentation.

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

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

The description states a specific verb and resource: it 'EXTRACTS the answer using ONLY what the tool result contains' after routing across 5,521 tools and 1452 sources. It clearly distinguishes itself from the sibling ask_pipeworx by being 'hallucination-resistant' and returning evidence, making the purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and provides examples like financial verdicts, legal claims, and medical lookups. It also states when not to use: 'prefer ask_pipeworx for casual lookups,' directly naming the alternative.

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

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

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?

Annotations only provide generic hints (readOnly, openWorld, idempotent), but the description adds substantial behavioral detail: account/paid-plan requirements, 1452 sources, parallel decomposition, return packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]), contradictions[], hop fields, semantic excerpting of large records, and expected latency of 15-90s. It does not contradict any annotation.

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

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

The description is long but information-dense, and every sentence contributes specifics (source count, exclusion of open-web, citation semantics, gap handling, latency). It is slightly less front-loaded than ideal because the account requirement is placed first rather than the core purpose, but the structure remains readable and well-organized.

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

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

Given the tool's complexity, no output schema, and only 2 parameters, the description is thorough: it documents what the findings packet contains, when gaps appear, how contradiction detection works, how citations are guaranteed fetchable, and the performance envelope. It gives the agent enough context to set expectations and correctly 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?

Even though schema coverage is 100%, the description adds meaningful meaning beyond the schema: it explains how depth levels behave (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative chasing) and clarifies that 'question' accepts broad/multi-part natural language because decomposition is the point. This helps the agent choose parameter values correctly.

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

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

The description clearly states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' in ONE call, explaining it decomposes the question into facets and routes them in parallel. It also distinguishes itself from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains depth-level selection (standard vs thorough) and that multi-step questions resolve in one call.

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?

Annotations already declare read-only, idempotent, non-destructive. The description adds extensive behavioral context: the compatibility_warning cases, temporal_alignment semantics, skipped_cross_type/subtype counters, and the fact that most pre-mapped topics return warnings. This gives the agent a clear model of what will happen and why.

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 every section (purpose, modes, response, safety fields, caveat) adds value. It's longer than average but justified by the tool's complexity. It is front-loaded with the core purpose and only moderately repetitive. Could be trimmed slightly, but not wastefully verbose.

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 response shape and safety fields, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning triggers, temporal_alignment, and skip counters. Together with the parameter modes, this is a complete and self-sufficient tool description for an AI 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%, but the description significantly enhances parameter understanding. It explains the topic macro list, that explicit tickers/slugs override the topic side, and gives concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'. This is far beyond the schema's plain field descriptions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which names both the specific resource (spread between two venues) and the function. It goes on to explain the two modes and the key behavior of flagging incompatible bet shapes, clearly distinguishing it from sibling tools like polymarket_arbitrage.

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 explains when to use the topic shortcuts vs explicit ticker/slug mode. It also warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. However, it does not explicitly mention alternative sibling tools for other use cases, so it stops short of a full 'when to use alternatives' guide.

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?

Annotations already mark the tool read-only and idempotent, but the description adds rich behavioral details: exact return fields per type, data sources (SEC EDGAR, RxNorm), citation URI schemes, auto-disambiguation, and internal cascading of endpoints.

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 examples, then states the core purpose, then details supported types with structured formatting, and ends with a performance note. Every sentence adds value; no fluff.

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

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

With no output schema, the description fully discloses return values for each entity type, including sources and citation URIs. It covers input flexibility, disambiguation, and the cascading nature of the lookup, making the tool self-contained 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?

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra meaning by explaining what each type resolves to, providing example values, and mentioning auto-disambiguation, which goes slightly beyond the schema.

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

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

The description uses a specific verb ('resolve') and a clear resource ('user-spoken NAME to the canonical/official identifier'), with concrete example queries. It distinguishes from siblings by emphasizing that it provides IDs other tools require as input.

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

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

Explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives natural-language usage examples and notes that it replaces 2-3 manual lookups, clarifying its value proposition.

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 (read-only, open-world, idempotent), the description discloses the dual-path routing (structured vs. grounded), the specific verdict values, the inclusion of pipeworx:// citations, and the fact that it replaces multiple sequential calls. This adds substantive behavioral context. Missing details like rate limits or failure modes, but annotations already cover safety.

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 segment earns its place: trigger phrases, usage guidance, routing logic, return summary, and a note on replacing sequential calls. The structure is logical and front-loaded. Slightly verbose, but justified for the tool's complexity.

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

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

Given no output schema, the description thoroughly covers return values (verdict, actual value, citation, reasoning), the routing decision, and tolerance behavior. It is complete for an agent to understand what the tool does, when to use it, what it returns, and how to configure key parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the claim parameter with examples and clarifying tolerance_pct's role as an override of implied wording, with explicit guidance for hallucination detection (1–2%). This additional context 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 opens with concrete NL trigger phrases and states the core function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes from siblings by specifying the company-financial SEC EDGAR fast path vs. the grounded pipeline fallback, making the tool's scope unmistakable.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It also differentiates between company-financial claims and other claims, guiding routing. However, it doesn't name alternative sibling tools or state when not to use it, so it misses explicit exclusions.

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