Arcgis Neworleans

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond annotations: default model (Workers AI Llama-3.3-70b, free), the BYO-key model for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This transparency helps the agent understand cost implications and expectations 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 tightly written—four sentences covering purpose, default behavior, return shape, and use cases. Information is front-loaded with the core verb and outcome. No redundant text. Slightly dense but well-structured; every sentence earns its place. A 4 reflects strong conciseness without being too sparse.

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 compensates by detailing the per-model response fields and the combined view. All four parameters are already covered by the schema (100% coverage). The description does not explain edge cases (e.g., what happens if _apiKey is passed without 'anthropic' in models), but the schema and description together give the agent sufficient information for safe invocation. With moderate complexity, this is adequately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: 'pass `_apiKey` to also probe Anthropic (BYO key — you pay Anthropic directly for those calls)' explains the _apiKey lifecycle and cost responsibility. It also states 'Omit for just workers-ai' for the models parameter, clarifying default behavior. This goes beyond schema descriptions, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes the tool from sibling tools like scan_competitor_ai_presence by its focus on per-model scoring and LLM knowledge probing rather than broader market scanning. The purpose is unambiguous and immediately actionable.

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

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

The description explicitly states use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to invoke the tool. It does not explicitly name alternatives or exclusions, but the use-case framing gives strong guidance. Given the rich sibling list, a brief mention of alternatives would push this to 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 indicate readOnly, openWorld, and idempotent behavior. Beyond that, the description adds useful behavioral context: it routes to sub-tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. This meaningfully enriches the agent's understanding of what happens when the tool is invoked.

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

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

The description is longer than average but front-loads the most important guidance and packs each section with useful routing criteria, alternatives, and examples. Some repetition exists in the example list and the 'use whenever' phrasing, but overall the structure earns its length for a default entry-point tool.

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

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

For a high-complexity tool with no output schema, the description covers the essential operational context: when to use it, when to step up to alternatives, what input it expects, what it returns, and how it behaves. The absence of an output schema is mitigated by the clear statement that it returns structured answers with citation URIs.

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 documents the question parameter and its aliases. The description adds value by clarifying that the parameter is a natural-language factual question and by giving diverse examples like 'current US unemployment rate' and 'adverse events for ozempic', which help the agent understand the expected input style.

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 core behavior: it routes factual questions to the right underlying source tool and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes this tool from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart without opening 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 is explicit about when to use this tool: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names concrete alternatives and the conditions that should trigger them, such as ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

The description adds live behavior beyond the annotations by stating candidate routing improvements are enabled when under test, none is currently active, and it is a full working router with no fallback. Since annotations already cover read-only/idempotent safety, this extra operational context is valuable and non-contradictory.

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 four sentences are front-loaded with identity, then current state, usage, and caveat. The 2026-07-26 retirement date is arguably more detail than needed, but each sentence contributes useful information and there is no filler.

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

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

For a single-question router with fully documented aliases, the description is functionally complete: it defines behavior, current parity with ask_pipeworx, and usage intent. It references but does not describe the response shape, relying on ask_pipeworx's definition, which is acceptable given no output schema exists.

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 all parameters are aliases for the same 'question' string. The description only repeats 'same arguments' and adds no parameter-level semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description opens by defining the tool as 'Beta version of ask_pipeworx: identical universal router' and specifies it routes across the same 5,884 tools with the same arguments and response shape. This clearly distinguishes it from sibling tools ask_pipeworx and ask_pipeworx_grounded through its experimental routing status.

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 an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains results are compared with the stable router, implying ask_pipeworx is the stable alternative, though it does not explicitly state when to avoid this beta or prefer ask_pipeworx_grounded.

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 signal read-only, open-world, idempotent behavior. The description goes well beyond that by disclosing latency cost, the exact success return shape with verbatim evidence, and the explicit refusal_reason enum when data doesn't directly answer. No stated behavior contradicts the annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return/refusal contract, usage trigger, and cost tradeoff. It is front-loaded with the most important information and well organized despite its 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?

For a tool with no output schema, the description fully specifies return structure on both success and refusal paths, names all refusal reasons, explains the cost implication, and gives concrete use cases. An agent has enough to select and invoke it correctly without additional information.

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 and its aliases. The description adds no parameter-specific semantics beyond the schema, so the baseline score 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 states a specific mode—'Hallucination-resistant answer mode for high-stakes reads'—and contrasts it with ask_pipeworx, naming the exact mechanism: same routing, then extraction using only the tool result. This clearly differentiates it from its siblings and removes ambiguity about what it does.

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

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

The description explicitly says when to use it ('whenever an answer will be quoted, cited, or acted on... must not invent facts'), gives concrete domains, and names the alternative ('prefer ask_pipeworx for casual lookups') plus the cost tradeoff. This is explicit when/when-not guidance.

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

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

The description reveals extensive behavioral details beyond the read-only/idempotent annotations: resolver contract with market_match_confidence, short-circuit on low-confidence matches, closed-market status handling, wide-spread tradeability warning, cancellation-rule risk, and news fallback attempts. It also warns agents to inspect match confidence before trusting analysis, adding significant operational context.

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

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

The description is long but appropriately sized given the tool's complexity. It is well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. Every sentence contains meaningful detail; no filler or repetition of schema fields.

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?

Without an output schema, the description takes full responsibility for explaining return shapes: result.market, result.analysis, result.evidence, parent_event extractor, and fallback fields. It also covers safety, resolution rules, and practical limitations (closed markets, wide spreads), making the tool fully understandable for an agent to invoke and interpret 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%, and the description adds crucial parameter behavior: it explains the three accepted input formats for market, the depth parameter (quick vs thorough fan-out), and include_raw with payload size implications. It also provides concrete examples for the market parameter, enriching the structured schema.

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

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

The description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly differentiates from siblings like polymarket_arbitrage or polymarket_edges by focusing on per-bet research with data pack fan-out, and it restates the purpose with concrete user intents ("should I bet on X", "what does the data say about Y").

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

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

Provides explicit usage examples: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It also describes when the tool blocks (low-confidence, closed markets). However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral detail: it pulls specific financial metrics (revenue, net income, cash, long-term debt) from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, and for drugs pulls FAERS counts, FDA approvals, and trial counts. It also discloses sorting behavior and the return of citation URIs, going far beyond the annotations. No contradictions found.

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

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

The description is longer than average, but every sentence serves a purpose: trigger phrases, core function, preference rule, type-specific behavior, sorting, and return format. It is front-loaded with the most critical info (what it does and when to prefer it), and the density is justified by the tool's complexity. Slightly wordy 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?

Given no output schema, the description compensates by explaining return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It also covers data sources and fiscal-year edge cases, making the tool's behavior clear for an agent. The 2–5 entity limit is already in the schema, so no gap there. The description fully covers the practical context needed 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?

Schema coverage is 100% and already documents both parameters (type enum, values array with min/max). The description adds extra meaning by linking type='company' to specific financial data sources and type='drug' to adverse-event and approval counts, plus giving concrete value examples (AAPL, MSFT, ozempic). This enhances parameter understanding beyond the schema, though not maximally since the schema was already quite informative.

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

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

The description clearly states a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides multiple trigger phrases ('compare X and Y', 'X vs Y', 'rank these companies') that make the tool's scope unmistakable. This distinguishes it from sibling tools like entity_profile, which handles single-entity 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?

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also explains the two modes (company vs drug) and indicates it replaces 8–15 sequential lookups, effectively stating when this tool is the superior choice.

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?

Although readOnlyHint/openWorldHint/idempotentHint already cover safety, the description adds substantial non-obvious behavior: parallel decomposition across 5,884 tools, gap[] never-invented behavior, hop field, citation_uri fetchability guarantee, semantic excerpting, contradictions[], expected latency, and account/plan gating. This far exceeds what annotations convey and materially shapes an agent's invocation and expectation.

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 long, but every sentence earns its place: account gate, alternative routing, data source scope, mechanism, return shape, gaps behavior, when-to-use guidance, depth semantics, citation guarantees, excerpting, latency. It front-loads the critical 'ACCOUNT REQUIRED' callout and the alternative-tool instruction before the detailed mechanics. One minor deduction for a stream-of-consciousness length that could be broken into tight paragraphs.

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 is a complex, high-latency, multi-call orchestrated tool with one required string param and a depth enum, no output schema, and many siblings. The description covers account prerequisites, auth, appropriate vs inappropriate use, depth semantics, return-packet shape, citation fetchability, gaps/hop/contradictions fields, excerpting, and latency expectations. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description genuinely raises it by explaining what the depth values mean in behavioral terms (quick=single hop, standard=gap recovery plus contradictions, thorough=iterative lead-chasing plus contradictions) and by clarifying that question may be broad/multi-part because decomposition is the point. It doesn't exhaustively restate schema descriptions, but it adds decision-useful 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 announces a specific verb and resource ('Grounded multi-source research across Pipeworx's 1536 STRUCTURED data sources') and distinguishes itself from open-web search and from ask_pipeworx. The phrase 'this is NOT open-web search' and the explicit 'Best for broad/multi-part questions' make the tool's role unmistakable even among 30+ siblings.

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

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

The description explicitly says when to use deep_research ('broad/multi-part questions over structured data') and when to prefer ask_pipeworx ('single lookup'; 'BREAKING or colloquial CURRENT-NEWS'). It also names the alternative tool directly, satisfying the when-not and alternatives criteria.

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, idempotent, and non-destructive behavior. The description adds valuable behavioral context: results include full input schemas with curated examples, ready to call directly, and 'no second schema lookup needed'—which clarifies the output format and operational convenience.

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 dense sentences with zero wasted words: the first defines the scope and domain coverage, the second explains the output and strategic use. The long list of domains is a set of concrete examples, not 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 description covers purpose, usage context, return format (names, descriptions, full schemas with examples), and operational advice ('call this FIRST'). For a discovery tool with no output schema, it provides all essential details an agent needs to invoke it correctly.

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

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

All six parameters are fully documented in the schema (100% coverage), so the description adds little beyond reinforcing that query is a natural-language description and mentioning 'top-N' relative to limit. Baseline 3 is appropriate since the schema carries the parameter 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 states the tool finds tools by describing a data or task, enumerates specific domains, and distinguishes itself as a discovery/entry point among siblings. The verb 'Find' plus the explicit resource ('tools') makes the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST' for option exploration. However, it does not name specific alternative tools or exclusion cases, so it falls short of the top bar.

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 readOnly/idempotent annotations, disclosing source-specific failure behavior (USPTO soft-fail), expected empty sections, resolved:false semantics for private companies, and the meanings of sources_used/sources_failed. No contradiction with annotations exists.

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

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

The description is long but dense and front-loaded with the most important usage signal (ALWAYS PREFER). Each section — examples, sources, return semantics, input forms, failure behavior — earns its place for a complex multi-source tool, with minimal redundancy.

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

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

For a tool with no output schema, the description thoroughly enumerates return sections, source coverage, fallback behavior, and data-failure semantics. It gives an agent everything needed to invoke the tool correctly and interpret its results without external documentation.

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

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

Even though schema coverage is 100%, the description adds substantial meaning: it gives examples for ticker, zero-padded CIK, and company name; explains that type values are interchangeable; and describes the EDGAR name-resolution behavior that affects the value parameter.

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

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

The description opens with concrete user phrasings ('Tell me about X', 'company profile for Microsoft') and names the exact function: a one-call, cross-source profile of a US public company. It clearly distinguishes the tool from single-pack lookups by emphasizing the parallel fan-out and holistic output.

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 directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when not to expect success (private companies, companies with only small-molecule drugs), so the agent understands when invocation is or isn't appropriate.

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 clearly indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutation. The description adds that it clears "previously stored memory" and can be used for sensitive data, but doesn't add further behavioral details like whether deletion is permanent or if there are any side effects. It doesn't contradict annotations.

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

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

The description is two sentences, well-structured, and front-loaded with the core action. Every word 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?

The tool is simple (one parameter, no output schema) and annotations provide the safety profile. The description covers the purpose and usage context. It doesn't explain return values, but that's unnecessary given the absence of an output schema. Sibling tools like remember and recall provide the surrounding context.

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

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

Schema coverage is 100%, as the only parameter 'key' is described as 'Memory key to delete'. The description adds the phrase 'by key' but doesn't go beyond the schema. The schema already does the heavy lifting, 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 states exactly what the tool does: "Delete a previously stored memory by key." This clearly defines the action (delete), resource (memory), and scope (by key). It also distinguishes from sibling tools remember and recall by indicating the opposite operation.

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

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

The description gives explicit usage conditions: "Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier." It also mentions pairing with remember and recall, implying these are complementary tools. However, it doesn't explicitly say when not to use it or provide direct alternatives, so it falls just short of a 5.

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

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

Annotations already declare this as read-only, non-destructive, and idempotent. The description complements this by revealing the internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses that output is a single text blob, adding context 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 three sentences: purpose, process, and use cases. It is front-loaded with the core action and contains no filler or redundant information. 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?

For a simple tool with two parameters, no output schema, and strong annotations, the description covers all necessary aspects: what it does, how it works, what it returns, and when to use it. It is fully self-contained for the agent.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' already clearly documented. The description does not add parameter-specific details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb-plus-resource: 'Generate a production-ready llms.txt file for any URL'. It clearly states the output format and names the intended consumers (AI crawlers like ChatGPT, Claude, Perplexity), distinguishing this tool from siblings focused on visibility checks or 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?

The 'Useful for' list provides three concrete scenarios: getting a client's site indexed, drafting for your own project, and auditing a competitor's AI visibility. This gives clear contextual guidance, though it doesn't explicitly mention when not to use the tool or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable context about what the tool returns (fields, geometry type, record count, capabilities) without contradicting annotations. It does not mention rate limits or auth, but the read-only nature is clear.

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 with no filler. Every phrase earns its place: 'schema by url', the list of returned elements, and the scope (Feature/Map Service layer). Efficient and well-structured.

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

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

For a simple one-parameter tool with no output schema, the description adequately explains the return values (fields, geometry type, record count, capabilities). It does not elaborate on what 'capabilities' includes, but the core information is present and sufficient for most use cases.

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 a single 'url' parameter fully described in the input schema. The description adds the phrase 'by url' which reiterates the parameter's role, but does not provide additional format or behavior details beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('an ArcGIS Feature/Map Service layer's schema by url'). It explicitly lists what the tool returns (fields, geometry type, total record count, capabilities), making it easy to distinguish from sibling tools like query_layer.

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 on when to use this tool: when you need schema-level information for an ArcGIS layer. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to imply usage. No misleading guidance.

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

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

The description adds that results are scoped to the caller and lists the exact fields returned (id, type, params, created_at, last_fired_at, fire_count). Annotations already declare readOnlyHint and destructiveHint false, so this supplements rather than repeats. No contradiction.

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

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

The description is three short sentences: action, return fields, and usage guidance. Each sentence adds value with no redundancy.

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

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

For a one-parameter read-only tool with rich annotations, the description covers what, what returns, and when to use it. The output fields are enumerated, and no additional context seems necessary.

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

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

The only parameter include_inactive is fully described in the schema (100% coverage). The description does not mention the parameter, so it adds no extra semantic value beyond the baseline.

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

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

States 'List the caller's active subscriptions' with a specific verb and resource. It also enumerates the return fields, making it clearly a read/list operation distinct from sibling tools like subscribe and unsubscribe.

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?

Says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving clear use cases. It doesn't explicitly name alternatives, but the context implies when this is appropriate (before mutations or cancellation).

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 all-false annotations, the description richly discloses behavioral traits: the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and how feedback is processed ('The team reads digests daily and signal directly affects roadmap'). This gives full transparency about side effects and follow-up 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 a dense, single paragraph that front-loads the primary purpose and then flows into usage, exclusions, and mechanics. Every sentence earns its place—there is no fluff—but the length is substantial and could benefit from bullet points or section breaks to enhance readability.

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

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

Despite having no output schema, the description explains the return value via claim_token and how to check resolution status. It covers prerequisites (which tools are eligible), edge cases (different server), rate limits, and data usage. The description is fully self-contained for a 4-param nested-object 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 parameters are documented. The description adds value by explaining the claim_token lifecycle with a concrete invocation example ('pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies the message content constraint ('don't paste the end-user's prompt'). It doesn't detail each param, but the schema handles those details, and the description reinforces the context parameter's purpose.

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

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

The description opens with a clear verb phrase 'Tell the Pipeworx team' and immediately specifies the resource (Pipeworx) and the action (reporting bugs, missing features, or praise). It explicitly enumerates use cases and distinguishes itself from other servers' tools: 'ONLY for tools served by this Pipeworx connection'. This clearly differentiates it from sibling research/query tools.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusion criteria for tools from other MCP servers and tells the agent how to verify ownership ('Pipeworx tool names are the ones this connection lists').

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral details: it is a 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and mentions caching behavior ('Cached 5min-1h depending on window'). This gives the agent a clearer understanding of data provenance and freshness.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value. The use-case list is well-structured and directly actionable, with no redundant or vague phrases.

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 low complexity (one optional parameter) and the absence of an output schema, the description fully compensates by explaining what is returned (top tools, top packs, total call volume), the data source, privacy implications, and caching. This is sufficient for an agent to understand the tool's behavior and results.

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

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

The schema description covers 100% of the parameter 'window', including its default and the tradeoff between shorter and longer windows. The tool description merely repeats the possible values (24h, 7d, 30d) without adding new semantics, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource that immediately distinguishes it from sibling tools like discover_tools or recent_alerts, which serve different purposes.

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

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

The description provides three explicit 'Useful for' scenarios, giving clear context on when to use this tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full 5.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and openWorldHint, the description adds substantial behavioral context: it walks child markets, checks date-axis thresholds, requires partition sums to ≈1, emits BUY/SELL signals when deviation >3pp, applies a placeholder filter, and performs a fill check against live CLOB depth. It also explains failure modes (realizable_edge_pp ≤ 0 means do not trade). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and mode selection, then uses labeled subsections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure complex details. Every sentence adds value—examples, thresholds, exclusions, and actionable warnings—with no filler or repetition. Despite being long, it is efficiently organized for quick scanning.

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

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

The tool has two optional parameters and no output schema, but the description fully specifies returning structures (opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered) and covers edge cases (null signal for high placeholder fraction, fill-check caveat). Given the tool's complexity, the description is sufficiently complete for an agent to call 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 descriptions cover 100% of parameters, but the main description goes further by providing concrete examples for each parameter (event slugs like 'fed-decision-may-2026', topic seeds like 'Strait of Hormuz traffic returns to normal') and explaining the behavioral difference between the two modes: single-event partition_check vs cross-event union scanner. This adds meaning well beyond the schema's basic type and description.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by listing its exact methodology and modes (trending_scan, event, topic). This goes beyond a generic statement and leaves no doubt about what the tool does.

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

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

The description gives explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also points to an alternative tool when the use case differs: 'For custom sizing use polymarket_fill_risk.' This is model-level usage 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 and destructiveHint=false, but the description adds substantial behavioral detail beyond this: edge_pp_net after slippage, Kelly caps at 0.25, 24h-move warnings, partition overround bias corrections, placeholder-slug filtering, and the fact that concentrated_longshot is 'rare-by-design' with relaxed gates. It also discloses caching (1h at KV level), response diagnostics, and the unreliability of Fed signals. This is exceptionally transparent.

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

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

The description is long, but every sentence carries dense, relevant information and it is well-structured with clear section headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It is front-loaded with a one-sentence summary. It loses a point for length, which could overwhelm agents, but the structure mitigates this.

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 must explain response structure—and it does thoroughly: top-level by_segment segments, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also covers caching behavior, slippage assumptions, and why segments may be empty. Given the tool's complexity, this description is remarkably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes above and beyond by grouping knobs semantically: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and explaining why min_kelly doesn't filter partition arbs while min_partition_leg_kelly does. It adds domain logic that clarifies the schema's dry parameter descriptions, making it clear how parameters interact.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and response segments. The purpose is unambiguous and complete.

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

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

The description states a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when not to rely on Fed bets (excluded from ranking due to unreliable signal). However, it does not explicitly name alternative tools or state exclusions like 'use polymarket_arbitrage for X', leaving some implicit differentiation.

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

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

With annotations already declaring readOnlyHint, openWorldHint, and idempotentHint, the description adds valuable behavioral context: the 60-day snapshot TTL, cache-miss snapshot writing causing gaps, and decay computed from daily closes net of default slippage. It also explains the response structure, which exceeds what annotations alone convey.

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

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

The description is several sentences but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence carries information, but the length is slightly more than necessary; it could be condensed. It is organized and front-loaded with the 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?

There is no output schema, so the description thoroughly documents the response fields (tracked, expired, snapshot_dates), their meanings, and limitations (TTL, daily closes). It even provides interpretation guidance (e.g., 'median lifespan is your competition clock'), making it fully self-contained.

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

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

Schema coverage is 100% for both parameters. The description repeats defaults and enum values already in the schema, only adding the 'snapshot family' concept and the 'cache-miss' reason for snapshot gaps. This adds minimal meaning beyond the schema, so the 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 clearly defines the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses a direct question it answers ('how long has this edge existed and is it shrinking?'). This distinguishes it from siblings like polymarket_edges (current edges) and 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 provides clear context: it explains that a fresh wide edge and a 3-week-old wide edge are different trades, implying when persistence/decay analysis is needed. However, it does not explicitly name alternative tools or state when NOT to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive; the description adds substantial behavioral detail: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and describes mode-specific semantics for size_usd. It also warns about thin books and forced directional risk, which goes beyond annotation metadata.

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 structured with mode-based sections and a direct usage directive. It front-loads the purpose and walks through both single-market and basket modes without filler, though its length and uppercase emphasis are somewhat heavy-handed.

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

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

Given no output schema, the description enumerates the principal return values for both modes, explains the two usage modes, and contextualizes when the tool is necessary. Minor undefined thresholds (e.g., '~$500') and overlap behavior (when both market and event are passed) are gaps, but overall it's highly 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% and each parameter already has a descriptive entry. The description adds the conditional requirement ('REQUIRES one of market or event'), clarifies side defaults in each mode, and explains how size_usd is interpreted differently (max spend vs target proceeds vs settlement notional). This elevates it beyond the baseline schema detail.

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 scope: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill execution risk rather than edge 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?

It explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names the alternative tools and explains the failure mode (partial fills converting arb into directional risk), making usage context unmistakable.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral detail: compatibility warnings can be present even with matched pairs, temporal_alignment null means unknown rather than aligned, unknown legs are never paired, and spreads are gross because Kalshi fees are not modeled. This exceeds what annotations and schema convey.

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

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

The description is long but well structured with labeled sections including TWO MODES, RESPONSE, and SAFETY FIELDS. Every section adds operational meaning, though some repetition of cautionary phrasing could be tightened without losing 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?

Despite having no output schema, the description specifies the response shape, safety codes, per-pair flags, skipped-unclassified outcomes, low-confidence pairs, temporal alignment semantics, and fee caveats. For a tool with this complexity, an agent has enough detail to call it correctly and interpret results safely.

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

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

Schema coverage is 100%, and the description goes well beyond it: it enumerates the exact topic shortcuts, clarifies that explicit parameters override the mapped side, and states that both modes run the identical matching logic. It also explains how to interpret flags and safety fields associated with the 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?

States a clear purpose: compute the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two distinct modes. It is specific about resource and scope, though it does not explicitly contrast itself with sibling tools like polymarket_arbitrage or polymarket_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?

Gives strong usage context: explains the topic shortcut mode, explicit ticker/slug mode, and warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly say when to use this tool instead of its Polymarket-focused siblings, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it returns attribute rows and geometry, and that the query is SQL-like. It doesn't mention potential errors or rate limits, but the annotation bar is low, and the added context is useful.

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

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

The description is concise (three sentences), front-loaded with the core action, and every sentence adds value—action, parameters, return type, and a usage tip. No fluff or repetition.

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

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

For a read-only query tool with six parameters and full schema coverage, the description sufficiently covers the main behavior, return value, and a key usage pattern. It doesn't explain response structure in detail, but the absence of an output schema and the richness of the schema make this acceptable.

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 explains each parameter. The description reiterates the parameter names and adds the 'SQL-like' framing and sampling tip, but these do not significantly deepen understanding of individual parameters beyond the schema.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, using SQL-like parameters. It distinguishes itself from siblings like search_datasets (which finds datasets) and layer_info (which likely describes metadata) by specifying the query action and its data source.

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 directs the agent to source the URL from search_datasets, which implies a workflow sequence. It also gives a practical sampling tip with where='1=1' and out_fields='*'. However, it does not explicitly mention when to avoid this tool or contrast it with alternatives, so it loses one point.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: listing all keys when omitted, scoping to identifier (anonymous IP, BYO key hash, account ID), and the lifecycle relationship with remember/forget. 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?

Three concise sentences cover the core behavior, use case, scoping, and sibling pairing without repetition. Information is front-loaded: the first sentence states exactly what the tool does. 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?

For a simple tool with one optional parameter, the description covers the main intent, usage scenario, and scoping. It does not detail return format or error behavior, but given the output schema is absent and the tool is straightforward, this is acceptable. A small gap remains in not stating what happens if the key does not exist.

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 description already explains the key parameter. The tool description adds the omit-to-list behavior and scoping context, reinforcing and extending the schema meaning. This exceeds the baseline 3.

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

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

The description opens with a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes it from the sibling tools remember and forget, and the behavior is unambiguous.

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

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

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and references the paired siblings ('Pair with remember to save, forget to delete'). It lacks an explicit when-not to use, but the guidance is sufficiently 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 states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing operation. This directly contradicts annotations readOnlyHint:true and idempotentHint:true. 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 four dense, purposeful sentences with no filler. Every sentence contributes: purpose, return format, filtering, mark_read effect, and alternative access method.

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 sketches return fields and covers filtering, mark_read, and a REST endpoint for scripts. Lacks auth/error details, but for a read tool with good annotations it is reasonably complete. However, the annotation contradiction weakens overall completeness.

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 giving a concrete type example ("sec_8k"), explicitly clarifying 'since' as ISO timestamp, and explaining the effect of mark_read, going beyond the schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly states the tool's action and resource. It then details what is returned (source, citation_uri, raw payload) and filtering options, making it distinct from siblings like list_subscriptions or 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 clear context for use (polling, script access via alternative endpoint) but does not explicitly contrast with alternative tools or state when not to use it. Lacks explicit exclusions, 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?

The description goes beyond annotations by detailing multi-source fan-out, GDELT→GNews fallback conditions, USPTO soft-fail due to API sunset, and the output shape (changes[], total_changes, citations). This gives a realistic picture of external dependencies and non-determinism, complementing the readOnly/idempotent 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?

The description packs substantial operational detail into a few sentences, front-loading the core purpose and then layering source details, fallback logic, and output format. The user-query examples add length but improve discoverability, and no sentence is redundant.

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

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

With no output schema, the description compensates by explicitly stating the return structure and citation URIs. It also explains data sources, fallback behavior, parameter formats, and the alternative tool, covering all needed context for a complex multi-source API tool.

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

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

The schema already documents all three parameters with 100% coverage, including accepted formats for `since` and examples for `value`. The description repeats the `since` format but adds no new semantic information beyond what the schema provides, so it stays at 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 real-world query examples and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the underlying data sources (SEC, GDELT/GNews, USPTO) and contrasts with entity_profile, making the purpose unmistakable.

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

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

It explicitly directs users to entity_profile when they need a static profile instead of a time-windowed feed, which is a clear 'use instead' instruction. The examples also imply the tool is for recent-change lookups, covering typical use cases. No other sibling alternatives are mentioned, but this is sufficient for the core distinction.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: memory is scoped by identifier, and persistence differs for authenticated (persistent) vs anonymous (24 hours) users. 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 sentences: first states the core action, second provides usage context with examples, third gives storage details and companion tools. Every sentence earns its place, no fluff, and the most important info is front-loaded.

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

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

For a simple two-parameter tool with rich schema descriptions and annotations, the description covers purpose, usage, persistence behavior, and related tools. No output schema exists, but return values are not critical for a save operation. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some examples of appropriate keys and values (e.g., 'resolved ticker', 'user preference') but largely repeats what's already in the schema. It doesn't meaningfully enhance understanding of parameter 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 clearly states the tool's purpose with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes from siblings by explicitly pairing with recall and forget, and provides concrete examples of what to save. This fully differentiates it from other tools in the family.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' and explains the benefit ('so you don't have to look it up again'). It also names alternatives (recall, forget) for related operations, giving clear when-to-use vs when-not-to-use context.

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

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

Annotations already convey read-only/idempotent safety, and the description substantially enriches behavioral context: it explains multi-source fallback behavior, graceful degradation of LEI/FIGI enrichment, explicit `unresolved` reporting, and the 'asserts nothing' behavior for ambiguous matches. This goes well beyond what annotations alone provide.

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

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

The description is long but not padded; each clause adds operational detail. It is front-loaded with usage examples and key guidance, and it organizes details around supported types. It could be slightly tightened, but the structure helps an agent locate the critical 'Use FIRST' rule early.

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

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

Despite having no output schema, the description explains what the tool returns (CIK, ticker, LEI, FIGI, RxCUI, citations), how ambiguous results are surfaced (`figi_candidates`), how unresolved identifiers are reported, and how fallbacks work. This is sufficient for an agent to know what to expect and how to handle edge cases.

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

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

Schema coverage is 100%, but the description adds significant meaning: accepted input formats for both entity types, concrete examples (AAPL, 0000320193, 'ozempic'), and a critical formatting warning about passing only the issuer name for bonds. It clarifies practical usage beyond the schema's short property descriptions.

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

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

The description names a concrete action (resolve names to official identifiers), a clear resource scope (company/drug identifiers), and illustrates the purpose with natural-language user prompts. It distinguishes this tool from siblings by stating it converts names to the IDs other tools require, which is distinct from 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 says 'Use FIRST whenever you have a name but need an ID', giving a direct usage rule. It provides context like when ambiguity appears and how to format issuer names correctly, but it does not explicitly name alternative sibling tools or state when not to use it beyond the general rule.

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, so the bar is lower. The description adds meaningful behavioral context by explaining it probes each entity with ai_visibility_check, ranks by score, and returns a structured list with score, confidence, and signal density. It doesn't contradict annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and includes a relevant example. It avoids redundancy with the schema while providing essential behavioral and return-value information. Every sentence earns its place.

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

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

The tool has no output schema, so the description's explanation of the return format (ranked list with score, confidence, signal density) is essential and provided. It also clarifies the relationship with ai_visibility_check and the entity semantics. It doesn't explicitly mention API key requirements for anthropic models, but that is covered in the schema. Overall, it is sufficiently 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?

With 100% schema description coverage, the baseline is 3. The description adds value by specifying that the first entity is the 'subject' while the rest are competitors, a semantic rule not present in the schema. It also reinforces the role of the models parameter and API key.

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 'Compare[s] AI visibility across multiple entities side-by-side' and describes the probing and ranking process. It distinguishes itself from the sibling tool ai_visibility_check by mentioning it probes with that tool, making it specific to multi-entity comparisons.

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

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

It gives a concrete use case for competitive AI-marketing audits and an illustrative question. While it doesn't explicitly mention alternatives or when not to use it, the description implies that ai_visibility_check is for single entities, which serves as a clear contrast. A slightly more explicit exclusion would elevate it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds crucial context beyond that: the composite fan-out across two external services, graceful degradation on partial failures, the 5-30s first-measurement delay from bundlephobia, and the sources_failed field listing timeouts. This gives the agent realistic expectations about latency and failure modes.

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 well-structured: purpose first, then when-to-use, then return shape, then ecosystem scope, then failure behavior. It is longer than strictly necessary but every sentence carries useful content. The front-loading of the core purpose and the clear list of fields make it easy to scan.

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

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

With no output schema, the description compensates by listing the exact summary fields, per-advisory details, links, and alternative versions. It also covers the NPM-only limitation and partial failure behavior. Missing elements like invalid-package error handling are minor for a tool of this complexity. The provided context is sufficient for an agent to understand what results to expect.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package and version). The description reinforces the meaning by giving examples like 'adding lodash' and mentioning scoped packages in the schema. Since the schema already fully documents the parameters, the description adds no new semantic information, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: a composite 'should I add this npm package' check, naming the exact data sources (deps.dev and bundlephobia) and the fields returned. This clearly distinguishes it from sibling tools, which are either broader research tools or unrelated network/prediction 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?

Explicit usage trigger: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides a clear exclusion: NPM-only in v1, with non-NPM ecosystems delegated to deps.dev:version directly. This tells the agent both when to use and when not to use this tool.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds value beyond that by specifying what data is returned (name, summary, record_count, owner/org, Feature Service URL) and how the output should be used, which is useful behavioral context not captured by annotations.

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

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

The description is two sentences: the first states the core purpose with examples, the second explains the output and chaining to other tools. Every word earns its place, front-loaded with the action and resource.

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 three optional parameters, no output schema, and rich annotations, the description provides sufficient context by detailing return fields and the intended follow-up workflow. It omits potential nuances like pagination or the default limit, but those are in the schema. Overall complete for a search/discovery 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds minimal semantic context by providing example query keywords ('parcels, zoning, public safety & city services') and mentioning 'owner/org' which loosely relates to org_id. It does not substantially enrich parameter understanding beyond the schema.

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

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

The description clearly states the tool searches City of New Orleans GIS open geospatial datasets by keyword, with specific examples of dataset themes. It also defines the return content and explicitly differentiates from sibling tools query_layer and layer_info by directing the output URL to those tools.

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

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

The description gives clear context on when to use this tool (for finding datasets) and implies alternatives by instructing to pass the resulting Feature Service URL to query_layer/layer_info for further data operations. However, it stops short of explicitly stating when not to use this tool or naming 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description adds significant behavioral detail beyond that: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flagging, and offset/similarity score returns. This transparently discloses implementation details and limitations 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?

Each sentence earns its place: purpose, examples, use-case, pairing, and technical constraints are condensed into a few dense sentences. The description is front-loaded with the core action and avoids fluff, making it easy to parse 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?

Despite the absence of an output schema, the description states the return format (top-N passages with character offsets and similarity scores) and notes the truncation flag. Combined with rich parameter descriptions and annotations, this makes the tool's behavior fully transparent for an agent to invoke 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%, so the baseline is 3. The description adds value by clarifying the `text` parameter as 'the text you already pulled (e.g. a SEC 10-K body, an article, a long tool result)' and reveals that longer inputs are truncated and flagged—context not present in the schema. This extra operational guidance justifies a 4.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource+scope that clearly distinguishes it from siblings like ask_pipeworx_grounded. It explicitly lists inputs (text, query) and outputs (top-N passages with character offsets and similarity scores), leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage context: 'Use when the record is too big to cram into the prompt' and explains the alternative/complement 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives a clear when-to-use and how-to-integrate with siblings, satisfying the dimension fully.

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, the description discloses behavioral details: requires OAuth, feed is always on, SMS requires verified phone and has a 10/day cap. It doesn't contradict the annotations, and it adds meaningful constraints for real-world usage.

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

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

The description is a single dense paragraph that packs in types, delivery channels, and requirements without unnecessary fluff. It is front-loaded with the purpose and uses semicolons to separate ideas efficiently.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers auth, subscription types, delivery methods, and return value. It omits webhook signing details, but the schema covers that, so overall it is substantively complete.

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

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

The schema already covers all parameters with detailed descriptions, achieving 100% coverage. The description adds some extra semantic (e.g., 'items:["5.02"] = officer change') but mostly mirrors the schema examples, so it provides marginal additional value.

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 'Create a proactive monitoring subscription to a live-data event stream,' which clearly states the verb and resource. It also mentions that it returns the subscription ID. This distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 specifies a prerequisite ('Requires a Pipeworx OAuth account') and explains that the feed is always on with a pull mechanism. It doesn't explicitly name alternative tools, but it provides enough context for when to use this subscription tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it returns category-bucketed examples, is drawn from a live catalog, and behavior changes when topic is omitted. There is 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 lengthy but front-loaded with example prompts and clearly organized. Every sentence contributes distinct information: purpose, categories, parameter behavior, and onboarding guidance. It is efficient for the richness of content, though slightly dense.

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 one optional parameter, no output schema, and strong annotations, the description covers purpose, usage timing, return content, categories, parameter effects, and relation to meta-tools. It is fully complete for the tool's complexity.

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

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

Schema coverage is 100% for the single optional parameter. The description adds extra semantics by providing concrete examples ('finance', 'pharma', 'betting') and explaining the consequence of omitting the parameter ('Omit for a cross-category spread'), which goes beyond the schema description.

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

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

The description clearly identifies the tool as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking' and specifies that it 'Returns category-bucketed example questions ... with the exact tool + argument shape that answers it.' This is a specific verb+resource definition that distinguishes it from sibling tools like ask_pipeworx and discover_tools.

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

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

The description gives explicit usage timing: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains parameter usage ('Call with no arguments ... or pass topic to focus'). However, it does not explicitly name alternatives or when-not scenarios, 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?

The description adds significant behavioral context beyond the annotations: it explains that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This directly addresses the mutation's side effects and aligns with the destructiveHint=false and idempotentHint=true annotations, enriching the agent's understanding.

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

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

The description is extremely concise—two sentences—with the action stated first, followed by ownership enforcement and behavioral effects. Every sentence adds value, and the structure is well-organized.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential context: the cancellation action, ownership constraint, and the deactivation behavior. It does not explain return values, but that is not critical for a mutation tool with these annotations. Overall, it is complete enough for an agent to invoke it correctly.

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

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

The schema already provides 100% coverage of the parameter description ('Subscription id (uuid) returned by subscribe'). The tool description adds no additional parameter semantics, so the baseline score 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 clearly states the action: 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription), and distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation.

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: 'Ownership is enforced — you can only cancel your own subscriptions.' This tells the agent when it is appropriate to use the tool and sets a precondition. It does not explicitly name alternatives or when not to use it, but the guidance is sufficient for this simple 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?

Beyond the read-only/idempotent annotations, the description discloses important behavioral semantics: the meaning of all six verdicts, that could_not_verify indicates a failed check and must not be shown as evidence, and that unsupported means no source covers the claim. It also explains the two execution paths (structured vs grounded) and that the tool is a single-call replacement for a 4–6 step pipeline.

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

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

The description is longer than average but tightly organized: trigger phrases, use case, routing details, return values, and caller warnings. It is front-loaded with purpose and each section earns its place, though it could be trimmed by condensing the verdict list and repeated examples.

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 values, and it does so thoroughly—listing verdicts, citation format, and reasoning. It covers error semantics, distinguishes could_not_verify from unsupported, and addresses the tool's relationship to sibling operations. Given the tool's complexity, the description is complete and self-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?

Although schema coverage is 100%, the description adds meaningful parameter context: tolerance_pct overrides the wording-implied tolerance, has a default capped at 5, and is recommended at 1–2 for hallucination detection. The claim parameter is illustrated with examples and tied to the routing logic. This exceeds a baseline 3 by providing usage-oriented 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 opens with explicit trigger phrases ('Is it true that…' / 'fact check' / 'verify the claim') and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes itself from siblings like deep_research or ask_pipeworx by narrowing the scope to factual claim checking and mentioning it replaces a multi-step pipeline.

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

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

The description gives explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details routing rules (SEC EDGAR for company-financial claims, grounded pipeline for anything else) and warns about could_not_verify not being evidence. However, it does not explicitly name alternative tools or state when not to use this tool in favor of another sibling.

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