Arcgis Honolulu

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b) is free, passing `_apiKey` incurs direct Anthropic costs, and it discloses the return structure. This goes beyond what annotations alone tell 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 three sentences, front-loaded with the core purpose and output, followed by cost implications and use cases. Every sentence earns its place with no redundancy or filler.

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

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

There is no output schema, but the description compensates by specifying the return format: per-model {score, confidence, signals, raw_response} plus a combined view. It also covers practical contexts and cost implications. While it lacks error-handling or rate-limit information, for a read-only probe the description is sufficiently complete.

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

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

Schema description coverage is 100%, with each parameter (entity, models, _apiKey, context) documented in the schema. The description reinforces the default model and BYO key behavior but adds no new parameter-level detail beyond the schema. Baseline 3 is appropriate when the schema fully covers parameter semantics.

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

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

The description uses a specific verb 'probe' with a clear resource ('one or more LLMs') and a concrete output ('score visibility (0-100) per model'). It is not a tautology and clearly states what the tool does. However, it does not explicitly differentiate itself from sibling tools like scan_competitor_ai_presence, which may overlap in purpose, so it stops short of full sibling distinction.

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 concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass `_apiKey` for Anthropic probing and notes the free default model. However, it does not explicitly mention alternatives or when-not-to-use scenarios, which would earn a 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the bar for additional context is lower. The description adds real value by revealing that the tool fills arguments, routes to one of 5,798 tools across verified sources, and returns stable pipeworx:// citation URIs. No contradiction with annotations; it just doesn't discuss rate limits or failure modes, which is acceptable here.

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 most useful guidance, but it is severely bloated: the same 'Use whenever... Examples...' block is repeated multiple times with no added information. This makes it much longer than necessary and undermines the structure, even though the opening paragraph is strong.

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 the redundancy, the description is functionally complete: it explains the input style, the covered domains, the routing behavior, and the output format with citation URIs. There is no output schema, so the description appropriately carries the return-value explanation. The only missing context is explicit routing among sibling ask_pipeworx variants, which is a minor gap here.

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%: the primary 'question' parameter and all five aliases are documented in the schema, so the baseline is 3. The description goes beyond the schema by giving trigger phrases and examples that clarify what kinds of natural-language inputs are appropriate, making the parameter semantics noticeably clearer.

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

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

The description clearly states that the tool routes factual questions to one of 5,798 sub-tools and returns a structured answer with citation URIs, so the core action and resource are concrete. It distinguishes itself from web search through 'PREFER OVER WEB SEARCH', but it does not explicitly differentiate itself from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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 with trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete example queries. It also names web search as the alternative to prefer this over, but it does not provide when-not-to-use guidance or compare against the other pipeworx 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?

It discloses the experimental nature, the current absence of an active candidate ('No candidate is active right now'), the exact behavioral equivalence to ask_pipeworx, and that responses are compared for merge decisions—all beyond the readOnly/idempotent annotations. It also preempts the fallback misconception by stating 'this IS a full working router, just the experimental edge.'

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 its core identity and then gives current-state and usage context. It is reasonably sized, though slightly redundant ('same 5,798 tools, same arguments, same response shape' repeats what 'currently matches ask_pipeworx exactly' already conveys, and the retirement date is an incidental detail that could be trimmed.

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

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

For a router with a huge surface area, the description strategically defers to a known sibling ('identical... as ask_pipeworx', 'same arguments, same response shape'), which is sufficient for correct invocation if the agent knows ask_pipeworx. It also covers current runtime behavior, experimental status, and lack of fallback, leaving no critical 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 description coverage is 100%, so the schema already fully documents the parameters and aliases (q, text, input) for question. The description only says 'same arguments' and 'same response shape,' which is useful context but adds no new semantic meaning about what the arguments are or how to format them 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 states a precise role: 'Beta version of ask_pipeworx' functioning as a 'universal router' with the same 5,798 tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling by focusing on experimental candidate routing improvements.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' which is a direct directive for when to select this tool over the stable sibling. It also explains why results are compared, giving the agent a full usage context with no 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial behavioral context: the answer is extracted only from tool results, refusals are explicit with enumerated reasons, and an extra LLM call is incurred. This gives the agent a clear mental model of what happens when data is absent, which annotations cannot express.

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

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

The description is information-dense but every sentence earns its place: purpose, routing mechanism, output/refusal shape, use cases, and cost trade-off. It is front-loaded with the core 'grounded' purpose and then builds logically, with 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 present, the description compensates by specifying the full return shape and the possible refusal reasons. It also covers usage context, failure behavior, and cost comparison, making it complete enough for an agent to invoke correctly and interpret results.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter plus all aliases (q, query, prompt, text, input). The description adds no parameter-level meaning, but with full schema coverage, the baseline of 3 is appropriate; the schema carries the semantic burden.

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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly specifies the verb (ask), resource (Pipeworx), and differentiating mode (grounded). It also explicitly contrasts with ask_pipeworx, naming the sibling and explaining the extra LLM call, so an agent can distinguish it without inspecting sibling schemas.

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: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also states when not to use it: '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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description goes far beyond by disclosing fan-out behavior, parallel execution, fallback mechanisms (e.g., '_fallback_attempted'), status codes like 'low_confidence_match' and 'market_closed_or_inactive', suppression of analysis fields on low confidence, illiquidity warnings, and resolution-rule risk. It even quantifies the 'market moved X.Xpp' warning. This gives a complete picture of behavior without contradicting annotations.

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

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

The description is long but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose. However, it is verbose, with some redundancy (e.g., 'both routes are BLOCKING, just different mechanisms') and could be tightened without losing value. It earns its length mostly, but a 5 would require cleaner editorial control.

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

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

With no output schema, the description carries full responsibility for explaining return values. It thoroughly documents result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event, news fallback fields, and various status codes. It covers edge cases (closed markets, wide spreads, low-confidence matches, cancellation rules) and provides actionable context for safe use. This is remarkably complete for such a complex tool.

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

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

Schema coverage is 100%, and each parameter already has a description. The tool description adds significant meaning beyond the schema: it explains that 'market' accepts slug, URL, or question text; clarifies that 'depth' quick vs thorough maps to evidence-source counts; and recommends default include_raw=false to keep responses under ~20KB. It also shows concrete fan-out examples (BTC, Fed, Hormuz, Yankees, etc.), enriching parameter understanding with real use cases.

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

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

The description states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly differentiates from siblings by focusing on bet research and says 'Use for "should I bet on X"...' which is distinct from edge tracking or arbitrage tools. The classifier list and fan-out examples further clarify scope.

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

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

The description gives clear usage context: 'Use for "should I bet on X"...' and provides detailed when-to-use guidance (e.g., 'Check this before sizing sports/esports/event-occurrence bets'). It mentions 'always inspect these before trusting the analysis block' and 'both routes are BLOCKING' as practical guidance, but it does not explicitly name alternative sibling tools for when not to use it.

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

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

Beyond the readOnly/idempotent annotations, it discloses data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, result sorting, and citation URI returns. This provides substantial behavioral context.

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

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

The description is dense but every sentence adds value: trigger phrases, entity types, data sources, sorting behavior, and efficiency gains. It is front-loaded with actionable usage guidance.

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 no output schema, the description explains return format (paired data + citation URIs), sorting, and type-specific behavior. It is thorough 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%, but the description adds domain-specific meaning: type='company' pulls 10-K financials, type='drug' pulls FAERS/FDA/trial data, and values are explained with examples. This goes beyond the basic schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific trigger phrases. It distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile.

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

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

It explicitly says to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities, and provides trigger examples. This gives clear when-to-use guidance and names the alternative approach it replaces.

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

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

Annotations already mark readOnlyHint and idempotentHint, and the description adds substantial behavioral context: account/paid-plan requirements, parallel routing across 5,798 tools, findings packet fields, gaps[] and contradictions[], hop field, citation_uri fetchability, semantic excerpting of large records, and expected latency of 15-60s. This far exceeds what the annotations alone provide.

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

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

The description is dense and information-rich but somewhat redundant: depth semantics and contradictions[] are explained twice, and the inserted 'Second-hop iteration' sentence reads as a compressed afterthought rather than a clean explanation. The front-loading of the account requirement and alternative is helpful, but the middle section could be better organized for agent comprehension.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so thoroughly: verbatim evidence, confidence, source, fetched_at, stable citations, explicit gaps[], contradictions[], hop field, and citation_uri guarantees. It also covers auth, paid plan constraints, throughput, and latency, making it unusually complete for a high-complexity tool.

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

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

Schema coverage is 100% and the schema already explains the depth enum and the question parameter's natural-language nature. The description adds value beyond the schema by clarifying that depth:'thorough' requires a paid plan, and by giving latency expectations and the reasoning that multi-step questions resolve in one call.

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: grounded multi-source research across 1517 structured data sources in ONE call, with parallel decomposition and routing. It also explicitly differentiates itself from open-web search and singles out ask_pipeworx for simpler lookups, so an agent can distinguish it from siblings without ambiguity.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples. It also names the alternative, ask_pipeworx, for single lookups and for users who are not signed in, and notes that depth:'thorough' requires a paid plan.

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 valuable behavioral context about the output—top-N tools with names, descriptions, and full input schemas with curated examples—and notes that results are directly callable with no second schema lookup. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with purpose and usage, followed by output format and invocation order. The domain list is long but directly relevant for query formulation, and each sentence contributes practical information. It is slightly longer than minimal but not wasteful.

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

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

For a read-only discovery tool, the description covers purpose, usage, output characteristics, and call order. There is no output schema, so the description's explicit mention of return contents (names, descriptions, full schemas) fills that gap. It is sufficient for an agent to invoke the tool correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for all six parameters, including aliases and examples. The description does not add parameter-specific details beyond what the schema already states; it mostly reinforces that 'query' is a natural language description, which the schema already explains.

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 'Find tools by describing the data or task', clearly stating the tool is a discovery/meta-tool. It enumerates specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from direct-answer tools by instructing to 'Call this FIRST' when many tools are available and wanting to see the option set, not just one answer.

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 is given: '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 does not name specific sibling alternatives for when not to use this tool, but the context is clear enough for an agent to decide.

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

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

The description goes far beyond the annotations by disclosing multi-source fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF; explains per-source soft-fail behavior; clarifies that empty sections are real 'no data'; and states exactly what happens for private companies. It also notes the USPTO sunset and the expected empty fda_products for small-molecule-only companies. This is rich behavioral context with no contradiction to the readOnly/idempotent 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?

Though long, the description is dense and front-loaded with examples and the core 'ALWAYS PREFER' usage guidance before detailing behaviors and failure semantics. Every sentence adds practical information about inputs, outputs, source behavior, or edge cases; there is 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 present, the description carries the full burden of explaining return structure, and it does so thoroughly: resolved flags, recent_filings with URIs, fundamentals, patents, federal contracts, FDA products, hiring, news, LEI, and sources_used/sources_failed. It also addresses edge cases like private companies, source failures, and expected empty sections. This is a complete operational description for a complex tool.

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

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

Schema coverage is 100%, but the description adds meaningful nuance beyond the schema: zero-padded CIK format, name resolution via SEC EDGAR, and that 'type' accepts 'company' or 'ticker' interchangeably. It even explains future expansion for person/place. The description substantially enriches both parameters.

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

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

The description clearly states the tool builds a 'full cross-source profile of a US public company in ONE parallel call,' with concrete user-phrase examples ('Tell me about X', 'research Acme', 'brief me on Tesla'). It distinguishes itself from chaining 'single-pack SEC/XBRL/news lookups.'

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted inputs (ticker, CIK, company name), notes that private companies yield resolved:false with a notes line, and signals 'person/place coming soon' as a current 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 already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds no new safety information. It adds some context about what gets deleted (a stored memory by key) and why (clearing sensitive data), but this is largely implicit in the schema and annotation. 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 three concise sentences. The first explains the action, the second gives usage guidance, and the third names related tools. Every sentence earns its place with no redundancy or filler.

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

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

For a simple one-parameter tool with strong annotations (destructive, idempotent) and no output schema, the description fully covers purpose and usage. It explains when to apply it (stale context, task completion, clearing sensitive data) and mentions related tools, leaving no significant gaps.

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

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

Schema coverage is 100%, with the single parameter 'key' described as 'Memory key to delete.' The description repeats this concept with 'by key' but does not add any additional meaning beyond the schema. Baseline of 3 applies.

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

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

The description begins with 'Delete a previously stored memory by key,' which clearly specifies the action (delete) and the resource (memory by key). It distinguishes this tool from siblings like 'remember' and 'recall' by positioning it as the deletion counterpart.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember and recall' to indicate related tools, but it does not explicitly state when not to use the tool or name an alternative for non-deletion scenarios.

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 transparently discloses the behavior beyond the annotations: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also describes the output as 'a single text blob ready to drop at site-root/llms.txt.' While the annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds useful process and output details. It stops short of mentioning potential limitations like robots.txt enforcement or network failures, but the core behavior is well covered.

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 earning its place: first sentence states the primary action and benefit, second explains the process/output, third lists use cases. It is front-loaded with the verb and resource, avoids fluff, and is highly scannable for an agent.

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, no output schema), the description is complete: it covers purpose, process, output format, and use cases. The output is explicitly described as a 'single text blob ready to drop at site-root/llms.txt', which compensates for the lack of an output schema. No critical information is missing for an agent to select and invoke the tool correctly.

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

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

The input schema already describes both parameters with 100% coverage (url and max_links). The description does not add specific semantic detail beyond the schema; it mentions 'any URL' and the output format, which indirectly relates to the url parameter, but max_links is not addressed. Per the rubric, high schema coverage means 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 explicitly states the tool's action: 'Generate a production-ready llms.txt file for any URL'. It names the specific resource (llms.txt), the target audience (AI crawlers like ChatGPT, Claude, Perplexity), and the outcome (indexing the site cleanly). This clearly distinguishes it from sibling tools, which focus on AI visibility checks or research rather than file generation.

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

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

The description provides three concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives clear context for when to use the tool, though it does not explicitly mention alternatives or when not to use it. A 5 would require explicit exclusions or alternative tool references.

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, covering the safety profile. The description adds value by specifying exactly what information is returned (fields, geometry type, record count, capabilities), which is beyond the annotations and aligns with them. 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 a single, front-loaded sentence that efficiently communicates the tool's purpose and expected output. Every word adds value with no redundancy or filler.

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

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

For a simple schema-retrieval tool with one parameter and no output schema, the description provides a sufficient list of the returned data categories (fields, geometry type, record count, capabilities). It is complete enough for an agent to understand what to expect without needing additional details.

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

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

The input schema provides full coverage for the single 'url' parameter with a clear description and example. The tool description adds nothing beyond repeating 'by url', so the schema carries the semantic burden. This aligns with the baseline of 3 for 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 'Get' and identifies the resource as 'an ArcGIS Feature/Map Service layer's schema'. It explicitly lists the returned details: fields (name + type), geometry type, total record count, and capabilities. This distinguishes it from sibling tools like query_layer, which likely retrieves data rather than schema.

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

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

The description clearly indicates this tool is for obtaining schema information by URL, making the usage context evident. However, it does not explicitly mention when not to use this tool or name alternatives directly, though siblings like query_layer imply data retrieval. This is a clear context without explicit 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 read-only, idempotent, non-destructive behavior. The description adds scoping (caller's subscriptions) and return field details, which are useful 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?

Two efficient sentences: purpose, return fields, and usage. 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?

The tool is simple, and the description covers purpose, output fields, and usage. Since there is no output schema, listing the return fields is sufficient.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, so the description gains no extra credit for parameters. It does not mention the parameter, but the schema fully covers it.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the return fields, and distinguishes it from sibling tools like subscribe/unsubscribe by framing it as a review/pre-cancellation step.

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 use cases: to review what you're monitoring before adding more, or to find an id to cancel. It lacks an explicit exclusion or named alternative, but the context is clear.

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

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

The description discloses key behavioral traits beyond the annotations: the claim_token mechanism for reading resolution status, a rate limit of 5 per identifier per day, and that it does not count against tool-call quota. These details are not present in the annotations and add significant value.

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 serves a purpose, covering usage, exclusions, claim_token, rate limits, and team processes. It is front-loaded with the primary purpose and well-structured, though slightly wordy in places, preventing a perfect score.

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

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

For a tool with no output schema, the description is remarkably complete: it explains the submission lifecycle, the claim_token response mechanism, how feedback is processed (daily digests, roadmap impact), and constraints. It covers all necessary context an agent would need to use and follow up on the tool correctly.

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

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

The schema covers all parameters with descriptions, but the description adds practical usage semantics, such as how to use the claim_token parameter ('pipeworx_feedback({claim_token:"pwfb_…"})') and guidance for the message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This goes beyond the schema's baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb + resource and distinguishes itself from sibling tools, which are research or query tools, by focusing on feedback submission.

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 specifies when to use the tool (bug, feature/data_gap, praise) and when not to use it ('ONLY for tools served by this Pipeworx connection'). It also provides an alternative action ('file it with that server instead') for tools from other MCP servers, making the guidance exceptionally 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?

Despite having strong annotations (readOnly, openWorld, idempotent), the description adds valuable behavior: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), return shape ('just (pack, tool, count)'), and caching ('Cached 5min-1h'). This goes well beyond the annotation hints.

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

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

Every sentence earns its place: lead result statement, three use cases, data provenance, and caching details. It is front-loaded with the core purpose, and the structure is logical and readable. No redundant text.

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

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

With no output schema, the description explains the return shape ('top tools, top packs, total call volume', 'just (pack, tool, count)'). It also covers caching, data source, and privacy, making it complete for a simple one-parameter tool with strong annotations.

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

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

The schema already provides full coverage (enum, description), but the tool description adds meaning by explaining trade-offs: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the parameter's semantics beyond the schema.

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

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

The description uses a specific verb 'Returns' and clearly identifies the resources: 'top tools, top packs, and total call volume.' It also distinguishes itself from sibling tools by focusing on aggregate trending signal from other AI agents, not direct search or discovery.

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

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

The description explicitly lists three concrete use cases—(1) discovering hot data sources, (2) confirming canonical tool choice before asking, (3) aligning with agent needs—which provides clear when-to-use guidance. The window parameter description also informs selection between short and long windows.

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

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

Beyond the readOnly/idempotent annotations, the description discloses mode-specific behavior, the ≥0.30 Jaccard semantic anchor, placeholder filtering, the partition_check output fields, and the fill-check against live CLOB depth. This is rich behavioral context with no annotation contradiction.

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

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

The description is long but front-loaded with the core purpose, then organized by mode and behavioral details in labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries operational value and there is no redundant 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 specifying the response shape (opportunities[], partition_check fields), and covers edge cases like placeholder-heavy partitions, low-similarity pairs, and unrealizable edges. It is self-contained for a complex arbitrage tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it gives concrete event slug and topic examples, explains what happens in each mode, and clarifies cross-event matching constraints and output behavior. This substantially enhances the schema's brief 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 opening sentence states a specific verb and object: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly names the resource and methodology, and the mention of partition-sum checks distinguishes it from sibling edge/fill-risk 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?

It explicitly says to call with NO args for trending_scan, pass event for single-market, or topic for cross-event scanning, and recommends event for a specific market. It also directs users to polymarket_fill_risk for custom sizing and warns not to trade when realizable_edge_pp ≤ 0.

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, and non-destructive hints, the description discloses substantial behavioral detail: model families and their formulas, edge calculations net of slippage, Kelly caps, tradeable-edge knobs, response diagnostics, warnings about 24h moves, and caching behavior. This is rich transparency that goes far beyond the annotations and explains anticipated 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 summary, but the rest is a dense block of technical detail with numerous nested clauses and examples. While every sentence contains relevant information, the lack of bullet points or clear segmentation makes it hard to skim. It is appropriately detailed for a complex tool but not concise.

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

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

With no output schema, the description fully specifies the response structure: top-level by_segment with three model families, fed_candidates, and _diagnostics (including funnel counters and filter_skips). It also explains edge fields, kelly values, market liquidity/spread, and the 24h move warning. This is comprehensive for a 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%, so baseline is 3. The description adds value by explaining how the knobs interact—for example, min_partition_leg_kelly is necessary because partition arbs have parent-level kelly_fraction_half=0, and the slippage rationale notes that Polymarket has zero fees but typical 20-50bp spreads. This contextual nuance justifies a 4.

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

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

The description states a specific action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the resource (Polymarket markets), the output (opportunities), and the differentiating value (discovery without paging hundreds of markets), 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 frames the tool for 'what should I bet on today' and highlights that it saves agents from paging hundreds of markets. It also gives a concrete limitation (Fed signal is unreliable and excluded from ranking). However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit 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 cover read-only, idempotent, open-world. The description adds extensive behavioral detail: edge_pp_net is signed (negative = SELL YES), trend categories, decay_pp_per_day computed on absolute value, expired opportunities, snapshot_dates semantics (cache-miss gaps), TTL limits, and reliance on daily closes vs. intraday. 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 but well-structured: a one-sentence definition, an illustrative question, explicitly labeled Args, RESPONSE sections (tracked, expired, snapshot_dates), and a LIMITS section. Every sentence contributes critical information—no fluff. Front-loaded purpose and clear organization justify a high score.

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

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

Given the tool has no output schema, the description fully explains return values and edge cases: tracked/expired/snapshot_dates, trend enum, decay calculation, snapshot gaps, TTL limits, and data provenance. It covers all aspects needed for an agent to invoke and interpret results correctly, exceeding standard descriptions.

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

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

Schema already has 100% coverage with descriptions for both parameters. The description adds marginal context by calling window a 'snapshot family' and restating defaults/max, but adds no significant new meaning beyond 'snapshot family' and slight clarification of clamp range. Baseline 3 is appropriate 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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It poses a specific question it answers ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges, distinguishing it from sibling tools like polymarket_edges that likely show current edges.

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

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

The description implies when to use this tool by explaining its unique value ('a 3-week-old wide edge is different trades') and details what it returns (tracked, expired, snapshot_dates). It does not explicitly name alternatives or say 'use this instead of polymarket_edges,' but the context makes the use case clear. Slight deduction for missing explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral detail: it walks the order-book ladder, returns top_of_book/vwap_fill_price/slippage_pp, identifies thin_legs, and explicitly discloses the dominant loss mode (partial basket fills converting into unhedged directional positions). 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 densely packed with operational value: it front-loads the core purpose, then clearly organizes content into SINGLE-MARKET and BASKET sections with explicit parameter interpretations, return fields, and risk notes. Every clause earns its place, and the structure aids navigation despite the length.

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

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

With no output schema, the description bears the burden of explaining return values, and it does so comprehensively: it lists all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, capture_ratio, profit_usd, thin_legs, forced_directional_risk, etc.). It also covers mode selection, defaults, clamping, and real-world failure modes, making it highly complete for a complex tool.

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

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

Schema coverage is 100% and each parameter has a descriptive schema entry, but the description adds critical mode-dependent semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also explains side defaults, including the auto behavior in basket mode, which goes well beyond the schema.

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

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

The description opens with a specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely defines the tool's function. It further distinguishes itself from siblings by explicitly naming polymarket_arbitrage and polymarket_edges and positioning this tool as the fill-risk validator, not the signal generator.

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 an explicit usage directive: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, warning that theoretical overround on thin books is not capturable and that partial basket fills create unhedged directional risk, which is excellent contextual guidance.

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

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

Annotations already show readOnly/idempotent behavior, and the description goes well beyond them by explaining compatibility codes, the meaning of `null` in temporal alignment, the non-consideration of Kalshi fees, the `skipped_unclassified` behavior, and the obligation to read safety fields even when matches exist. This is rich and non-contradictory 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 text is dense and information-rich, but it suffers from long paragraphs, heavy use of inline lists, and a wall-of-text structure. Nearly every sentence has information, yet the utility could be improved with clearer sections, bullet-like token groupings, and tighter phrasing.

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

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

There is no output schema, so the description carries the full burden of explaining return semantics; it names `top_spreads_pp`, compatibility fields, temporal alignment object, `skipped_unclassified`, `low_confidence_pairs`, `fees_note`, and counters. It covers the large majority of what an agent needs to correctly interpret and use the tool.

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

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

Schema coverage is 100% could be considered a baseline, but the description materially extends parameter meaning: it enumerates the ten macro shortcuts, explains that explicit tickers/slugs override the mapped side, and clarifies that both modes run the identical token-overlap process. An agent receives enough context to choose valid parameter combinations.

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 cross-venue operation ('Cross-venue spread between Kalshi and Polymarket for the same resolving question') and acts participants, pricing units, and caveats. It clearly distinguishes this tool from single-venue or arb-focused siblings by naming the two venues and the concept of equivalent bet shapes.

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

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

The description gives clear mode-level guidance: `topic` for pre-mapped shortcuts, explicit ticker/slug for custom pairings, and both run the identical matcher. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped is not tradeable, though it does not explicitly name alternative sibling tools to use instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating it 'Returns attribute rows (and geometry)' and reveals parameter-style behaviors (SQL-like where, comma-separated out_fields), which is valuable beyond the annotations.

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

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

The description is two sentences and every part adds value: the action, the source workflow, the key parameters, the return type, and a practical usage tip. No fluff or redundant information.

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

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

For a 6-parameter tool with no output schema, the description covers the key aspects: what it does, how to use it, and what it returns. It lacks detailed output format (e.g., GeoJSON vs JSON) but provides enough context to select and invoke the tool correctly. The reference to search_datasets helps with the full workflow.

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

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

Schema coverage is 100%, so the schema already fully documents all parameters. The description adds minor clarifications like 'SQL-like' for where and 'comma-separated' for out_fields, but these are redundant with schema descriptions. It does not introduce new meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Query') and resource ('ArcGIS Feature Service / Map Service layer'), clearly distinguishing this tool from siblings like layer_info (metadata) and search_datasets (dataset discovery). It also outlines key parameters and return type, making the purpose unambiguous.

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

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

The description explicitly references 'from search_datasets' indicating the intended workflow, and provides a practical sampling tip ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly state when not to use this tool versus alternatives or mention exclusion cases.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and lifecycle pairing, going beyond the structured hints.

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

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

Three dense sentences, front-loaded with the primary action, followed by use-case, scoping, and lifecycle guidance. No redundant wording.

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?

Covers both operational modes (retrieving a specific key vs listing all keys), scope, and related tools. Lacks return format details, but for a simple read tool with no output schema, the description is sufficient.

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

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

Schema coverage is 100% and already explains the key parameter. The description enhances semantics with concrete key examples (user's target ticker, address, research notes), helping the agent infer appropriate key values.

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

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

The description opens with a specific verb-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly differentiates from sibling tools by explicitly naming remember and forget, and provides concrete examples of stored keys.

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

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

It provides an explicit use case: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names complementary tools: 'Pair with remember to save, forget to delete,' giving the agent clear decision criteria on when to use this tool.

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

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

Description contradicts annotations by disclosing mark_read:true mutates read state, while readOnlyHint=true indicates a read-only operation. This is a direct annotation contradiction.

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

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

Single paragraph packs purpose, return fields, filtering, mark_read behavior, polling, and alternative endpoint without waste. Slightly dense but every sentence adds value.

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

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

Covers return payload characteristics, filtering options, read-tracking semantics, and alternative URL for scripts. Given no output schema, this is sufficient for a straightforward feed reader, though the contradiction with annotations reduces trust.

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

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

Schema covers all parameters with descriptions; description adds a concrete example type ('sec_8k'), clarifies ISO timestamp format, and explains the effect of mark_read and unread_only beyond the schema.

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

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

Description states 'Pull fired events from your subscription feed' with a specific verb and resource. It clearly explains the return fields and filtering, distinguishing it from siblings like list_subscriptions and recent_changes.

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 context for polling and an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools. It implies usage for alert retrieval but lacks explicit when-to-use/when-not-to-use guidance.

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

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

Beyond annotations, it discloses critical behavior: fans out to SEC EDGAR, GDELT→GNews fallback (with specific conditions), and USPTO soft-fail due to API sunset. It also notes single parallel call and citation URI output, providing rich operational insight.

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

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

The description is front-loaded with user intents and then systematically covers function, sources, parameters, return format, and alternative. It is somewhat dense but every sentence adds value, and the structure aids comprehension without waste.

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 (changes[] grouped by source, total_changes, pipeworx:// citation URIs) and covers sources, fallbacks, soft-fails, and `since` formats. It is comprehensive for a tool of this complexity and clearly identifies when to use a sibling.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a minor recommendation ('Use "30d" or "1m" for typical monitoring') and confirms that `since` accepts relative shorthand, but largely repeats schema descriptions without significant extra meaning.

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

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

The description clearly defines the tool as a 'change feed for a company in the last N days/weeks/months' with a specific verb and resource. It also distinguishes itself from entity_profile by explicitly naming the alternative for static profiles, making its purpose unmistakable.

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

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

The description provides explicit usage context with natural language intents ('What's new with X') and states when to prefer entity_profile instead ('when you want the static profile... regardless of window'). This gives clear guidance on tool selection among siblings.

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

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: key-value pairs scoped by identifier, persistence differences for authenticated vs. anonymous sessions (24 hours), and the pairing with recall/forget. This enriches the agent's understanding of storage semantics without contradicting 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?

Three sentences, each earning its place: sentence one states the core purpose, sentence two provides usage guidance with concrete examples, and sentence three covers persistence and related tools. Well-structured, front-loaded, and free of 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 store tool with two well-documented parameters and idempotent annotations, the description is nearly complete. It covers usage, persistence, and relationship to sibling tools. The only notable omission is explicit mention that storing to an existing key overwrites the previous value, but this is a minor gap given the idempotentHint annotation.

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

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

The input schema already provides comprehensive descriptions for both parameters (key and value), yielding 100% schema coverage. The description adds only a minor detail ('scoped by your identifier') but doesn't materially enhance the parameter understanding beyond what the schema already conveys, so a 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 opens with a specific verb ('Save') and resource ('data the agent will need to reuse later'), clarifying its scope across conversations and sessions. It distinguishes itself from sibling tools by explicitly referencing 'recall' to retrieve and 'forget' to delete, firmly establishing its unique role in the memory suite.

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

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

Provides clear when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives directly ('Pair with recall to retrieve later, forget to delete'), giving explicit context for when this tool is appropriate versus its siblings.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavioral details: multi-source cascade lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguous results returning 'figi_candidates', and explicit reporting of unresolved identifiers. This gives the agent accurate expectations about output variability.

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 example queries and a clear 'Use FIRST' directive, and it is organized by supported types. It is quite long and dense with parenthetical caveats, but nearly every detail earns its place given the tool's complexity.

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

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

There is no output schema, so the description carries the burden of explaining return semantics. It covers expected output fields ('figi_candidates', 'unresolved'), identifier sources, fallback behavior, and input edge cases, giving an agent enough context to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by introducing ISIN as an accepted company input (not present in the schema) and by explaining type-specific resolution behavior. However, much of the value parameter guidance already appears in the schema's rich descriptions, so the incremental contribution is moderate.

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: resolving user-spoken names to canonical/official identifiers that other tools require as input. It clearly enumerates supported types ('company', 'drug') and gives concrete example queries, making it easy to distinguish from siblings like entity_profile or compare_entities.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID' and lists acceptable input forms and entity types. It does not explicitly name sibling alternatives or state when not to use the tool, but the routing guidance is clear enough 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 readOnlyHint and idempotentHint. The description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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?

Three sentences, each packed with useful information: purpose, method, use case, and output. No filler words or repetition.

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

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

Despite lacking an output schema, the description discloses the return format (ranked list with score, confidence, signal density). It covers the input (entities, models, key, context), the process (probes, ranks), and the use case. Complete for a comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the first entity is the 'subject' for narrative and the rest are competitors, which is not in the schema. It also provides an example for context.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb 'Compare' and resource 'AI visibility'. It distinguishes itself from sibling ai_visibility_check by focusing on multiple entities and ranking them.

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

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

Provides a clear use case: 'competitive AI-marketing audits' with an illustrative example. It implies single-entity checks would use ai_visibility_check, but does not explicitly state when not to use this tool, so it falls short of a 5.

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

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

Annotations already show read-only and non-destructive, but the description adds valuable behavioral details: it fans out across two services, returns a specific summary block, and handles partial failures gracefully. It even notes the 5-30s delay for first bundlephobia measurement and that sources_failed will indicate timeouts.

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 detailed but every sentence adds value: purpose, usage, output, ecosystem scope, and failure handling are all covered without fluff. The structure is logical and front-loaded with the main purpose.

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

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

Given the tool's complexity (composite of two services) and no output schema, the description fully compensates by enumerating the summary fields, per-advisory details, links, and alternative versions. It also covers edge cases (partial failures, timeouts) and ecosystem limitations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra context beyond the schema: explains the composite fan-out behavior, mentions NPM-only scope, and lists the exact output fields, which helps infer parameter impact. It also adds an example ('lodash') that clarifies usage.

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 deciding whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the exact use case and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on dependency analysis.

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 when to use: whenever the agent asks about safety, popularity, or size of an npm package. It also gives an exclusion: NPM only in v1, with a fallback to deps.dev:version for other ecosystems. This provides clear guidance vs 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 cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the exact output fields (name, summary, record_count, owner/org, url) and the next-step workflow, which goes beyond the annotation information without contradicting it.

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 sentence states the action and scope, the second explains the return format and downstream tool usage. No redundant information, fully front-loaded.

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

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

With no output schema, the description fully accounts for return values and the follow-up action (passing the URL to query_layer/layer_info). Combined with solid annotations and a small, clearly-documented parameter set, the tool is well-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%, so all three parameters are already well-documented. The description does not add new parameter-level semantics beyond what the schema provides, but it offers relevant examples of valid keywords (parcels, zoning, flood) which slightly enriches the query parameter context.

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

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

The description clearly states a specific verb ('Search') and resource ('Honolulu GIS open geospatial datasets') with concrete examples (parcels, addresses, zoning). It also distinguishes itself by explaining that the output is dataset metadata with a URL to be passed to query_layer/layer_info, setting it apart from those sibling tools.

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

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

The description provides clear usage context: use this tool to find datasets by keyword, then pass the returned Feature Service URL to query_layer or layer_info. It implies a workflow but does not explicitly state exclusions or mention when not to use this tool relative to other siblings like discover_tools or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: return values include 'character offsets and similarity scores,' enabling verbatim quote verification, and technical specifics like 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This goes well beyond the annotations and discloses truncation and windowing behavior, which is valuable for an agent. 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 five sentences and dense, but every sentence serves a distinct purpose: definition, usage, when-to-use, pairing, and technical constraints. It is front-loaded with the core function and avoids fluff. It could be slightly trimmed, but the length is justified by the tool's complexity. This earns a 4 rather than 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?

This tool lacks an output schema, so the description must explain what the agent will receive. It does: 'get back the top-N passages with character offsets and similarity scores.' It also covers input limits (200K chars with truncation flagging), the embedding/window approach, and when to use the tool. Combined with the annotations, the description covers all operational aspects an agent needs to decide and invoke correctly. It 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 coverage is 100%, so the baseline is 3. The description reinforces the 'text' parameter as 'the text you already pulled (e.g. a SEC 10-K body, an article, a long tool result),' which adds real-world context, but the schema already contains the same examples. It does not introduce new parameter-level meaning beyond what the schema provides. The truncation note is behavioral rather than semantic for the 'text' parameter. Thus, a 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly stating the verb (search) and resource (a fetched record). It differentiates from siblings by explicitly pairing with ask_pipeworx_grounded and emphasizing it operates over already-retrieved text, not external queries. This is a specific, distinguishing purpose.

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 the record is too big to cram into the prompt.' It also names an alternative workflow, 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document,' which clearly positions it relative to sibling tools. This is exactly the kind of exclusion/contextual guidance expected.

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 auth requirements, SMS verification, and the 10/day cap, adding behavioral context beyond annotations. It also states that the feed is always on. It doesn't discuss idempotency, but the annotation already covers that.

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

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

The description is lengthy but front-loaded with the core purpose and structured into types/delivery. Some redundancy exists with the schema's delivery details, but no sentence 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 rich schema, the description explains the return value (subscription id), prerequisites, all supported types, and delivery nuances, making it complete even without an output schema.

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

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

The schema covers all parameters at 100%, but the description enriches semantics with examples like 'items:["5.02"] = officer change' and clarifies delivery constraints. This lifts it above the baseline.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly differentiates from siblings like list_subscriptions and unsubscribe by focusing on creation, and details the supported subscription types.

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

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

The description provides clear context: requires a Pipeworx OAuth account, lists supported types, and explains delivery options. It does not explicitly name alternative tools or list when not to use it, so it misses the 'when-not' guidance needed for a 5.

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

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

Beyond the safe-read annotations (readOnly, idempotent), the description discloses the return shape (category-bucketed questions with tool shapes), the effect of the topic parameter (focus vs. full spread), and that it draws from the live catalog of thousands of tools. This adds substantial behavioral context that annotations alone do not provide.

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

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

The description is dense but front-loaded with example queries and packs function, usage, and parameter behavior into a single paragraph. While every sentence carries information, the structure is a run-on with em-dashes; splitting into clearer sentences would improve readability without losing content.

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

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

For a simple one-parameter tool with comprehensive annotations and no output schema, the description fully covers the return value (category-bucketed questions with tool shapes), call patterns (with/without topic), and when to use it first. The sibling context further supports tool selection, making the description complete for this tool's complexity.

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

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

The schema already covers the topic parameter fully (100% coverage) with its list of focus areas and 'Omit for a cross-category spread.' The description adds examples ('finance', 'pharma', 'betting') and reinforces the behavioral effect (no args = full spread, topic = focus), providing modest enrichment beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It explicitly distinguishes itself from siblings like ask_pipeworx (actual queries) and discover_tools by positioning itself as the 'FIRST' step, making its purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also names alternative tools (ask_pipeworx, entity_profile, compare_entities) for learning meta-tool usage, providing clear context for tool selection.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=true), the description adds valuable context: ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This fully discloses side effects and aligns with annotations.

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

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

Two concise sentences, each packing meaningful information. The first states the core action, the second clarifies ownership and side effects. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, ownership constraint, side effect, and the relationship to recent_alerts. This is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The schema already fully describes the sole parameter id as 'Subscription id (uuid) returned by subscribe.' The description adds no new parameter-level detail beyond restating 'by id', so baseline 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, and differentiates from siblings by explaining that the row is deactivated rather than deleted, so historical events remain available.

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 provides a prerequisite (the id returned by subscribe). It does not explicitly name alternatives or exclusions, but the sibling list and phrase 'by id' give sufficient 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 already provide read-only/idempotent hints, but the description adds critical behavioral context: return verdicts, the distinction between 'could_not_verify' (pipeline failure, not evidence) and 'unsupported' (no source exists), and the presence of verification_error details. This prevents misinterpretation of failure modes and goes well beyond the annotations.

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

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

The description is longer than typical but each section earns its place: query patterns, use-case, routing logic, return values, and a critical caller warning. It is front-loaded with the purpose and structured logically. It could be trimmed slightly (e.g., 'Replaces 4–6 sequential calls' is extra), but overall it remains focused and readable.

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

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

Despite no output schema, the description fully explains what callers can expect: the exact verdict enumeration, a grounded/structured value with citation, and reasoning. It also covers two distinct processing paths and clear failure semantics, making it complete for a 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%, already documenting both claim and tolerance_pct well. The description adds extra semantic value by explaining the default tolerance cap (5), suggesting 1-2 for hallucination detection, and providing example claim formats. This enhances the schema without redundancy.

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: natural-language claim verification against authoritative sources. It begins with concrete query patterns ('Is it true that…', 'fact check') and identifies the resource (claims) and action (verify). This distinguishes it from sibling tools like deep_research or ask_pipeworx_grounded by focusing specifically on fact-checking rather than open-ended research.

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

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

Explicitly instructs 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing for company-financial vs other claims. However, it does not name alternative tools or specify when NOT to use it, so it lacks a full exclusion/alternative list.

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