Arcgis Washingtoncomn

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

Beyond the readOnly/destructive hints, the description adds valuable behavioral context: the default model is free (Workers AI Llama-3.3-70b), calling Anthropic requires a BYO key with direct billing to the user, and the return structure is specified (per-model score/confidence/signals/raw_response plus combined view). 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 three sentences, front-loaded with the core action, and every sentence adds value: purpose, defaults/billing, return format and use cases. 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 tool with 4 parameters and no output schema, the description sufficiently covers invocation (what to pass, defaults), behavior (read-only probe, billing implications), and return value shape. The agent can confidently select and call this tool without further 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining the default model, how _apiKey enables Anthropic probing, and the purpose of context for disambiguation. It enriches parameter understanding beyond raw schema definitions.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the output (visibility score 0-100 per model). It distinguishes the tool from siblings by focusing on LLM awareness scoring for brands/topics, which is unique among the listed 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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide _apiKey for Anthropic. However, it does not explicitly mention alternatives or exclusions, so it stops short of the highest 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond these: it returns stable citation URIs, routes to sub-tools, works on every tier, and is a single fast call. It does not contradict annotations and enriches the safety/behavior profile.

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

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

The description is lengthy but well-structured and front-loaded with the key directive. Each section earns its place: preference over web search, routing behavior, examples, and escalation paths. Slight verbosity is justified given the tool's role as a default entry point, but it 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?

With no output schema and high complexity (5,521 tools, many siblings), the description fully compensates by explaining the return format (structured answer with citation URIs), when to use it, when to escalate, and providing domain examples. It gives an agent everything needed to select and invoke correctly.

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

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

Schema coverage is 100% with all six parameters documented; five are aliases for the main 'question' parameter. The description's examples reinforce the natural-language usage but add little semantic detail beyond what the schema already provides. The baseline of 3 is appropriate.

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

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

The description states a specific and unambiguous purpose: it answers factual questions by routing to one of 5,521 tools across 1,452 verified sources, returning structured answers with stable pipeworx:// citation URIs. It explicitly differentiates itself from web search and sibling tools (ask_pipeworx_grounded, deep_research) by stating its role as the default entry point.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with concrete alternatives for grounded answers and deep research. It also lists common query patterns and examples, making it clear when to invoke this tool vs. siblings.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable context about its experimental nature, current state (no candidate active), and that it fully works. This goes beyond annotations without contradicting them.

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

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

The description is dense but well-structured, front-loading the 'beta' identity and relationship to ask_pipeworx. Every sentence contributes purpose, usage, or status, but the inclusion of specific dates and tool counts makes it slightly heavy; still appropriately concise.

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

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

The description covers what the tool is, when to use it, its relationship to the stable version, current experimental status, and response shape equivalence. With no output schema, it adequately addresses the tool's complexity and operational 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 description coverage is 100%, with all six parameters (question and five aliases) fully described in the schema. The description does not add parameter-level details beyond saying 'same arguments' as ask_pipeworx, so it relies on the schema as expected.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded siblings by emphasizing its experimental routing improvements.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared to the stable router. It also clarifies there is no fallback, making the usage context unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial context beyond that. It details refusal behavior with specific refusal_reason values, explains that the answer is extracted only from tool result content, and discloses the extra LLM call cost. This goes well beyond the annotations and helps the agent predict edge cases.

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

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

The description is dense but every sentence conveys critical information: purpose, mechanism, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core value proposition and structured logically from what it does to when to use it. 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?

The tool has no output schema, so the description correctly takes on the burden of explaining return values. It specifies the success shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null} AND the failure shapes with each refusal_reason enum. It also covers performance tradeoffs and use cases, making the description complete for a complex tool with simple parameters.

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

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

The input schema has 100% coverage, documenting 'question' and five aliases (q, text, input, query, prompt) in detail. The description does not add parameter-specific semantics beyond noting 'Your question in natural language,' which is already in the schema. With full schema coverage, baseline 3 applies; no extra value is provided.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's specific verb (answer/extract) and resource (Pipeworx data). It explicitly distinguishes itself from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains.' This is a specific, differentiated purpose.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives an alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is clear and actionable.

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

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

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description goes far beyond by disclosing resolver contracts (match confidence, alternatives), short-circuit paths for low-confidence/closed markets, illiquid spread warnings, cancellation-rule parsing, and news fallback mechanics. This level of operational detail is exemplary and gives agents strong behavioral expectations.

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

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

The description is long but every sentence carries actionable information. It uses clear all-caps section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to structure complex content. Each section addresses a distinct aspect (filters, output, safety, edge cases) without redundancy, making the density justified.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains return shapes (market, analysis, evidence), resolver contract (match confidence, alternatives, suggestions), parent_event extractor, news fallback fields, blocking statuses, and cancellation-rule risk. It leaves no major ambiguity for an agent deciding whether to trust the 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 schema already fully documents the three parameters (market, depth, include_raw). The description adds real-world examples of market input formats and explains the tradeoffs of include_raw (response size) but does not introduce meaning beyond what the schema provides. Therefore, baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also distinguishes the tool from siblings like polymarket_edges and ask_pipeworx by focusing on bet-resolution data fan-out. The classifier list and fan-out examples further clarify the unique scope.

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

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

The description explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples by category. However, it does not explicitly name alternative tools to use instead, nor does it state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description goes further by disclosing data sources (SEC EDGAR/XBRL, FAERS), handling of fiscal years, result sorting, and return format (paired data + citation URIs). No contradiction with annotations.

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

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

The description is dense but well-structured, starting with trigger phrases, then core functionality, type-specific details, sorting behavior, and output. Every sentence adds value; no fluff.

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

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

Despite no output schema, the description covers what is returned (paired data + citation URIs), sorting, and the nature of data for each type. It also addresses a common edge case (off-calendar fiscal years). Complete for a read-only comparison tool with rich annotations and schema.

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

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

Schema covers 100% of parameters, but the description adds significant meaning: explains what 'type=company' vs 'type=drug' pull, provides examples for values, and clarifies the parallel call semantics. This goes well beyond the bare schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one call, with specific metrics per type. It distinguishes from siblings by explicitly saying to prefer it over sequential single-pack lookups when comparing 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?

Provides strong usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives query examples ('X vs Y', 'rank these companies'). It also distinguishes company vs drug use cases, making it clear when to invoke this tool.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: account requirements and paid tier, expected latency (15-60s, up to ~90s), the guarantee that gaps[] are returned rather than invented answers, citation_uri resolvability conditions, hop field, contradictions[] behavior, and semantic excerpting of large records. This goes far beyond what annotations provide and 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 and dense, but every sentence carries useful information for a complex tool. It is front-loaded with the critical account requirement and provides clear structure via semicolons and explicit comparisons. It could be trimmed slightly (some depth details repeat the schema), but the verbosity is justified by the tool's complexity and the need for behavioral transparency.

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 research tool with no output schema, so the description must explain return values, behavior, and edge cases. It does so thoroughly: the findings packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, citation_uri conditions, latency, auth, and fallback alternatives. The description is complete enough for an agent to select and invoke the tool correctly even without an output schema.

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

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

The input schema already covers both parameters comprehensively (question and depth with full enum descriptions, 100% schema description coverage). The description does reinforce depth semantics (standard re-angles gaps, thorough chases leads) but largely repeats schema information. It adds negligible new parameter-level meaning beyond the structured schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources... in ONE call'. It distinguishes itself from siblings by explicitly noting it is 'NOT open-web search' and comparing with ask_pipeworx for single lookups. The verb 'research' plus the resource (structured data sources) and the facet-decomposition behavior make the purpose unmistakable.

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

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

The description gives explicit usage guidance: best for 'broad/multi-part questions over structured data', with examples like comparing regulatory/financial exposure. It also provides clear exclusions: 'For a single lookup use ask_pipeworx' and for breaking/current news 'prefer ask_pipeworx'. It even handles account-tier fallback (use ask_pipeworx if not signed in). This is exemplary when-to-use framing with named 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas, and explicitly states results are 'ready to call directly, no second schema lookup needed.' 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 four sentences with a clear structure: purpose, list of use cases, return format, and guidance. It is information-dense and front-loaded, but the long domain list could be slightly trimmed 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?

For a discovery tool with 6 parameters and no output schema, the description explains the return format (names, descriptions, schemas) and the 'ready to call' behavior, which substitutes for an output schema. It lacks explicit pagination or error handling details, but these are likely not critical for a search tool.

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

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

Schema coverage is 100% and the schema richly documents each parameter (query, aliases, limit, defaults). The description adds only the 'top-N' concept, which is already implied by the limit parameter. Since the schema does the heavy lifting, 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 clearly states 'Find tools by describing the data or task' – a specific verb and resource. It distinguishes from siblings by listing concrete domains (SEC, FDA, FRED, etc.) and positioning itself as a meta-tool for tool discovery, which no sibling 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?

Explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at when not to use it ('not just one answer'), effectively steering agents toward specific tools when they already know what they need.

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, openWorldHint, idempotentHint, false destructive), the description discloses critical behavioral traits: it fans out across multiple sources, returns up to 5 recent filings with pipeworx URIs, sorts fundamentals by period_end DESC, and notes that the USPTO PatentsView API sunset May 2025 and will soft-fail until reactivated. It also clarifies that only tickers or zero-padded CIKs are accepted, with names explicitly unsupported. These are non-obvious behaviors not inferable from schema or 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?

Although longer than average, the description is dense with high-value information and every sentence earns its place. It is front-loaded with example queries, then clearly states the core function and return structure, and ends with essential constraints. No filler or redundancy – just necessary detail for a complex tool.

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

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

With no output schema, the description must convey return values, which it does in detail: cik + company_name, recent_filings with URIs, fundamentals (latest 10-K), patents, news mentions, and LEI. It also covers failure modes (patent API sunset) and prerequisites (must have ticker/CIK, not name). For a tool with this complexity, the description is complete and 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 description coverage is 100%, so the baseline is 3. The description adds value by providing realistic input examples ('AAPL', '0000320193'), explaining the unsupported name case and pointing to resolve_entity as a workaround. It also gives semantic context that the 'type' parameter is restricted to company today and future types are planned. This goes beyond mere schema repetition, earning a 4.

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

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

The description opens with concrete query examples ('Tell me about X' / 'research Acme' / 'brief me on Tesla') and then states the precise function: 'full cross-source profile of a US public company in ONE parallel call.' This clearly distinguishes it from sibling tools by emphasizing the holistic, one-call nature and listing the specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It also contrasts with alternatives like resolve_entity for names, cementing its unique purpose.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an explicit alternative: 'use resolve_entity first if you only have a name' for name-based inputs. This clearly tells the agent when to use this tool vs. alternatives, including the condition 'holistic view' and the exclusion for names.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds context about the nature of the data (sensitive) and the lifecycle of memories. While it doesn't elaborate on idempotency or missing keys, it complements the annotations well 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?

Two sentences with the primary action front-loaded and usage guidance immediately after. Every word contributes value, making it highly concise and well-structured.

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

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

For a simple delete tool with one parameter and annotations covering safety, the description is complete. It covers purpose, usage conditions, and related tools, and the lack of output schema is not a gap given the straightforward nature of the operation.

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 clear description for the key parameter. The description reiterates 'by key' but adds no additional semantic detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes from siblings like remember and recall by explicitly naming them as partners for other operations.

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

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

It provides explicit when-to-use guidance: stale context, task completion, or clearing sensitive data. The mention of pairing with remember and recall implies when to use alternatives, giving clear usage context.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds process details (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown, single text blob), which goes beyond the annotations. However, it does not discuss error handling or network prerequisites.

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 at four sentences, each serving a distinct purpose: purpose, process, output, and use cases. There is no redundancy or fluff, and it is front-loaded with the action verb.

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 clearly states the output as 'a single text blob ready to drop at site-root/llms.txt'. It covers functionality, process, and use cases. While it omits error behavior or edge cases, the tool's simplicity (2 params, clear output) makes this sufficiently complete.

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

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

The input schema provides full descriptions for both parameters (url and max_links with defaults and limits), achieving 100% schema description coverage. The description does not add additional parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL', and specifies the exact output format and intended use. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns total record count and capabilities, which provides some context beyond a simple 'read-only' label. However, it does not disclose potential performance costs of the count operation or any authentication requirements.

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?

A single, information-dense sentence that front-loads the purpose and enumerates the exact output fields. No filler or redundant 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?

For a simple metadata retrieval tool with one parameter and no output schema, the description adequately communicates what the tool returns (fields, geometry type, record count, capabilities). This is sufficient for an agent to invoke it correctly without further explanation.

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% for the single 'url' parameter, which is well-described as a Feature/Map Service layer URL with an example. The description repeats 'by url' but adds no new format details, so it meets the baseline without elevating the score.

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' with a clear resource: 'ArcGIS Feature/Map Service layer's schema'. It lists exact return components (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that likely retrieve actual feature data.

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

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

The description clearly indicates when to use this tool: when needing a layer's schema/metadata by URL. It does not explicitly exclude alternatives or mention when not to use it, but the context is clear enough for an agent to select it over query_layer or search_within.

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

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

With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds context by stating the return fields and the 'caller's' scope. It does not contradict annotations and provides useful behavioral detail beyond the schema.

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

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

The description is two sentences: the first states the function and return fields, the second gives usage guidance. It is front-loaded, concise, and every sentence earns its place.

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

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

The tool is simple with one optional parameter, rich annotations, and no output schema. The description explains the return fields and usage context, making it fully adequate for an agent to select and invoke the tool correctly.

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

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

The schema covers the sole parameter 'include_inactive' with a clear description, achieving 100% coverage. The tool description adds no additional meaning for this parameter, 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 uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also lists the return fields, making the tool's purpose unambiguous.

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

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

The description provides clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it does not explicitly mention alternatives or 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 are minimal (all false hints), so the description carries the burden. It discloses rate limits (5/day), that it is free and quota-free, and describes the claim_token lifecycle. This goes well beyond the structured annotations and sets accurate expectations.

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

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

The description is thorough but presented as a dense wall of text; every sentence earns its place, though bullet points would improve scannability. Front-loaded purpose and tight content justify a 4 rather than 3.

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 and a nested object parameter, the description covers key operational details: scoping to Pipeworx tools, follow-up token flow, rate limiting, and the team's review cadence. It proactively addresses likely agent questions, making it effectively 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%, providing a baseline of 3. The description adds value by explaining how claim_token should be used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by advising not to paste end-user prompts, which enriches the message parameter semantics.

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

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

The description opens with a specific action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the exact categories (bug, feature, data_gap, praise). It clearly distinguishes from sibling tools by stating it is ONLY for tools served by this Pipeworx connection, unlike other MCP servers.

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

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

Explicit when-to-use guidance is provided for each feedback type, plus a clear exclusion: reports about tools from other MCP servers should be filed elsewhere. It also explains follow-up usage via claim_token and rate limits, giving complete decision rules.

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 disclose read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, content structure (pack, tool, count), and cache freshness (5min-1h). This goes beyond the annotations without contradicting them.

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

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

The description is compact and well-structured. It opens with a clear purpose, lists specific use cases in a numbered format, and includes necessary behavioral details without fluff. Every sentence adds value, making it highly efficient.

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 and no output schema, the description covers key aspects: what is returned, the optional window, use cases, data source, and cache behavior. It lacks a formal return format but is complete enough for selection and invocation.

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

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

Schema coverage is 100%—the only parameter 'window' is fully described with enum values and explanation of behavior. The description repeats this information but adds no new semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a window. It uses a specific verb ('Returns'), identifies the resource (Pipeworx trending usage), and distinguishes itself from siblings by focusing on AI agent call trends rather than general discovery or Q&A.

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

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

The description provides explicit use cases: discovering hot data sources, confirming canonical tools before asking questions, and checking alignment with agent needs. It implies when to use the tool but does not explicitly name alternatives or state when not to use it, 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 readOnly/openWorld/idempotent, but the description adds rich behavioral context: Jaccard similarity threshold, partition placeholder filter, fill check against live CLOB depth, and explicit 'do not trade it' when realizable edge ≤ 0. No contradictions with annotations; this exceeds the baseline.

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 structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the main purpose. Every sentence adds value: mode selection, thresholds, response fields, and trading warnings. This is appropriate for a multi-mode tool with such detailed behavior.

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 is highly complete for a complex tool: it explains all inputs, output structures (opportunities[], partition_check, fill_check fields), safety filters, and even when to delegate to polymarket_fill_risk. Since there is no output schema, this detailed textual description fully compensates and equips the agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and both 'event' and 'topic' have descriptions, so baseline is 3. The tool description goes beyond schema with examples (like 'fed-decision-may-2026'), notes that full URLs are accepted, and explains the semantic difference between the two modes (single-event vs cross-event). This adds meaningful context but the schema already carried the primary definitions.

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

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

The description opens with a clear verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It then distinguishes three modes (trending_scan, event, topic), which separates this from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. It also recommends event for specific markets and points to polymarket_fill_risk for custom sizing, clearly guiding the agent to 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure including diagnostics, why a segment may be empty, and the 24h-move warning that 'your edge may already be in the price.' It also exposes the limitations of the Fed signal and the 'rare-by-design' nature of concentrated longshots. This is rich behavioral context with no contradictions.

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

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

The description is long but well-structured with all-caps section headers that break it into purpose, model families, knobs, and response format. It is front-loaded with the main purpose. Some details (e.g., specific alpha values, prior run parameters) are possibly over-specified, but most sentences add useful operational context for an agent. Overall, it is appropriately detailed for the tool's complexity.

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

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

There is no output schema, so the description must explain the return shape fully. It covers top-level response fields (by_segment, fed_candidates, _diagnostics), why a segment could be empty, how knobs affect filtering, and how to interpret the output. It even warns about the 24h-move case. This is a complete description for a tool with 9 parameters and no output schema.

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

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

The schema covers 100% of parameters and each has a description, so the baseline is 3. The tool description adds extra meaning by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining important nuances like why min_kelly does not apply to partition overround opportunities and how min_partition_leg_kelly works differently. This goes beyond the schema's per-parameter 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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which is a specific verb+resource+outcome statement. It also states the use case ('what should I bet on today') and explicitly distinguishes this from related tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on event-driven model edges rather than pure arbitrage or tracking.

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

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

The description clearly frames when to use this tool ('agents discover opportunities without paging hundreds of markets') and explains how to configure it via tradeable-edge knobs. It does not explicitly name alternative tools for excluded cases, but it provides strong context and even warns against relying on the Fed signal, implying when that part of the output is unreliable.

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 fully discloses data provenance and limitations: snapshots are only taken on cache-miss ('gaps mean nobody scanned that day'), history is bounded by a 60-day TTL, and decay is calculated from daily closes rather than intraday data. These are important behavioral traits that go well beyond the benign readOnlyHint, providing the agent with necessary interpretation 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 structured with clear labels (Args, RESPONSE, LIMITS) and every sentence contributes unique information. It is verbose in places, but the depth is warranted given the absence of an output schema and the need to explain the response format and edge cases.

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

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

Given the tool's complexity (no output schema, telemetry data with multiple response fields), the description goes above and beyond by enumerating the return objects (tracked, expired, snapshot_dates) and their key fields (edge_pp_net series, trend, decay_pp_per_day, lifespan_days). It also covers operational constraints like TTL and snapshot gaps, making it fully self-contained for an agent.

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

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

The schema already has 100% coverage for both parameters, but the description adds semantic value with 'snapshot family' for window, clarifying that it selects a family of snapshots rather than a time window. It also confirms the days lookback default and max, reinforcing the schema without contradicting it.

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

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

The description opens with a clear mission: 'Edge persistence and decay telemetry' and articulates the key question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling polymarket_edges by emphasizing it's built from daily snapshots and focuses on historical persistence rather than current values.

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 clear context for when to use the tool: when you need to understand edge persistence and decay, with the concrete example comparing fresh vs. 3-week-old edges. It does not explicitly name alternative tools for when not to use it, but the 'built from daily polymarket_edges snapshots' distinction implies a complementary role rather than a replacement for polymarket_edges.

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 well beyond the annotations (readOnlyHint, idempotentHint, etc.) by describing the actual behavior: it 'walks the ladder' on the order book, returns specific metrics like top_of_book, vwap_fill_price, slippage_pp, shares_filled, and warns of the risk that 'partial basket fills convert an arb into an unhedged directional position.' It also discloses the identification of forced_directional_risk. This rich operational detail is not present in 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 lengthy, but it's well-structured with clear sections for single-market and basket modes, and it front-loads the core purpose and usage requirements. Every sentence carries critical safety, output, or mode-specific information. While it could be tightened, the density is justified by the tool's complexity and the absence of an output schema.

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

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

Given there is no output schema, the description fully compensates by enumerating output fields for both modes (e.g., top_of_book, vwap_fill_price, shares_filled, capture_ratio, thin_legs, max_clean_notional_usd, forced_directional_risk). It also explains edge-case risks like overround on thin books and the dominant loss mode from partial basket fills. This is a complete and self-sufficient explanation of 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 covers all parameters with descriptions, so the baseline is 3. The description adds meaningful semantic distinctions: for `size_usd`, it clarifies different meanings in single-market (max spend on buys, target proceeds on sells) vs. basket (settlement notional — shares per leg), and explains the `side` default auto behavior in basket mode. It also highlights the mutual-exclusivity of `market` and `event`. This additional context enhances 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 opens with a specific and clear purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly positions itself as a pre-trade validation for signals from sibling tools (polymarket_arbitrage, polymarket_edges), clearly distinguishing its function. The verb-resource pairing is unambiguous and comprehensive.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It further details the two modes (single-market vs. basket) and the required inputs for each, giving clear context on when each mode is appropriate. This goes beyond mere implication and offers actionable direction.

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 readOnlyHint annotation by disclosing specific behavioral details: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type/subtype counters, and the direction of the spread calculation (Kalshi − Polymarket). This gives the agent a rich understanding of edge cases and failure modes without the need to invoke the tool.

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

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

The description is long but densely packed with useful operational caveats, modes, response structure, and warning semantics. It is front-loaded with the core purpose and uses ALL-CAPS labels for key fields, making it scannable. Every sentence contributes information, though it could be trimmed for brevity without losing critical nuance.

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 complexity of the tool (cross-venue comparison, many failure modes) and the absence of an output schema, the description is remarkably complete. It describes return values (leg-by-leg prices, top_spreads_pp), safety fields, temporal alignment, and skipped comparison counters, covering the essential context an agent needs to use the tool correctly.

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

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

The schema already documents all three parameters with 100% coverage, including the topic enum values and explicit ticker/slug override behavior. The description adds meaningful context by explaining the two modes, that explicit parameters override topic-mapped sides, and how the response leg-by-leg prices map to the input parameters. This is above baseline.

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

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

The description specifies a concrete resource ('Cross-venue spread between Kalshi and Polymarket') with a clear verb implied by 'spread' and differentiates it from siblings like polymarket_arbitrage by focusing on same-question cross-venue comparisons. It also clearly states the two operating modes, making the tool's function 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 provides explicit guidance on when to use each of the two modes: the 'topic' shortcut vs explicit event tickers/slugs. It also warns that pre-mapped does not mean tradeable and explains when the spread is a real signal. However, it does not directly compare against sibling tools or explicitly state when not to use this tool in favor of an alternative, stopping 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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations: it mentions the return format ('returns attribute rows (and geometry)'), the SQL-like query syntax, and pagination parameters ('limit', 'offset'). This is meaningful additional information about what the tool does.

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

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

The description is two sentences, front-loaded with the core purpose, and includes all necessary usage context without redundancy. Every phrase earns its place: the source of the URL, key parameters, return type, and a practical tip. It is concise and well-structured.

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

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

Given the complexity (6 parameters) and the absence of an output schema, the description covers the essential context: what the tool does, where the URL comes from, how to use the key parameters, and what it returns. It does not delve into error handling or output formatting, but the schema and annotations fill in details. This is a high level of completeness for a query 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 description coverage is 100%, with each parameter already having a description. The description reinforces the semantics by collectively referring to them as 'SQL-like' and lists their order, but adds little beyond the schema. The sampling tip is usage guidance rather than parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It uses a specific verb (Query) and resource (layer), and distinguishes itself from siblings by referencing search_datasets as the source of the URL. It also specifies the return type ('attribute rows (and geometry)'), which further clarifies its role.

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 for when to use the tool: it queries a layer 'from search_datasets', implying it follows dataset discovery. It provides a practical sampling tip ('Use where="1=1" + out_fields="*" to sample') which guides usage. However, it does not explicitly mention when not to use it or alternatives like layer_info, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context about scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all saved keys. This exceeds the baseline but does not fully detail edge cases like missing key 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 three sentences, front-loaded with the core action ('Retrieve a value...'). It efficiently covers the optional argument, use cases, scope, and related sibling tools without unnecessary fluff. Every sentence earns its place.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers operation, usage context, scope, and relationships to sibling tools. It explains what is returned (a value or list of keys) sufficiently for an agent to use it correctly.

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

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

Schema coverage is 100% with the key parameter already described as 'Memory key to retrieve (omit to list all keys)'. The description goes slightly beyond by providing examples of what keys might represent (user's target ticker, address, research notes), enhancing the agent's understanding of key semantics without adding technical syntax beyond the schema.

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

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

The description uses the specific verb 'Retrieve' and clearly identifies the resource as previously saved values/keys. It explicitly contrasts with sibling tools by naming 'remember' and 'forget' as paired operations and clarifies the optional key omission to list all keys, fully distinguishing its purpose.

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

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

The description explicitly states when to use: to look up context the agent stored earlier without re-deriving it from scratch. It names alternatives ('Pair with remember to save, forget to delete') and provides concrete example use cases (target ticker, address, research notes), giving clear 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?

The description directly contradicts the annotation readOnlyHint:true by stating 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This implies a persisted state mutation, which is a write operation. No other side effects or behavioral caveats are disclosed, and the contradiction makes the description unreliable.

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 well-structured, starts with the primary action, and each clause adds useful information without excess wordiness. It is slightly dense (combining return fields, filtering, mark_read, and polling guidance) but remains readable and purposeful.

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 listing the key fields returned (source, citation_uri, payload). It covers filtering, mark_read behavior, and polling. The main gap is no explicit mention of 'limit' or 'unread_only', but these are adequately documented in the input schema, so the description is sufficiently complete for a straightforward retrieval 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 description coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing a concrete example for 'type' (sec_8k), clarifying that 'since' is an ISO timestamp, and explaining the practical effect of 'mark_read' on subsequent calls. It does not repeat all parameter details but supplements them meaningfully.

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

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

The description opens with a specific verb phrase 'Pull fired events from your subscription feed' and clearly identifies the resource ('your persisted feed'). It further distinguishes the tool by noting returned fields (source, citation_uri, raw payload), making its purpose unambiguous compared to 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?

The description provides concrete usage context: it explicitly states that polling works, explains how to use mark_read for incremental reads, and offers an external HTTP endpoint as an alternative for scripts/dashboards. It does not explicitly name sibling tools as alternatives, but the guidance is clear enough for an agent to decide when to use this tool.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description adds crucial behavioral details: fans out in parallel, per-source fallbacks, PatentsView API sunset causing soft-fail, and the return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). These go well beyond the boolean hints and are valuable for an agent invoking the tool.

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

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

The description is a single dense paragraph that front-loads natural-language query examples, then efficiently packs in sources, date handling, fallbacks, and output format. Every sentence contributes information; there is no filler or redundancy.

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

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

Given the tool's high complexity (multiple data sources, fallbacks, failure modes) and the absence of an output schema, the description is remarkably complete. It covers inputs, source behavior, fallback triggers, the PatentsView sunset issue, and the output structure (changes[], total_changes, citation URIs), leaving little ambiguity for correct invocation.

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

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

Schema covers 100% of parameters, so the description need not repeat them. However, it adds practical value with concrete examples of ISO dates vs relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' for typical monitoring, which helps an agent choose appropriate values beyond what the schema specifies.

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

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

The description starts with concrete query examples, then states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It names specific sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly differentiates from sibling tool 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?

The description tells when to use this tool vs alternatives by stating 'Use entity_profile instead when you want the static profile...' It also explains fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and the USPTO soft-fail, which helps the agent decide when and how to rely on the 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 cover idempotency and non-destructiveness, but the description adds valuable behavioral context: 'scoped by your identifier' and persistence details ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). This goes beyond what annotations express, clarifying how the memory behaves across sessions.

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

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

The description is five sentences, each earning its place: purpose, usage examples, storage mechanics, persistence behavior, and companion tools. It is front-loaded with the primary action and contains no filler or repetition.

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

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

For a simple 2-parameter tool with no output schema, the description covers all necessary ground: what it stores, when to use it, how data is scoped, retention policy, and related tools. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both 'key' and 'value' already described with examples. The description adds no new parameter-specific semantics beyond calling it a 'key-value pair', which is already implicit in the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's action ('Save data the agent will need to reuse later') with a specific resource (key-value memory). It also distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete', which differentiates it from the related 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 with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and names the companion tools (recall, forget) as alternatives/complements. This leaves no ambiguity about appropriate invocation.

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 annotations already declare readOnlyHint=true and idempotentHint=true, the description adds significant behavioral detail beyond that: it specifies the exact outputs (ticker, CIK, company_name, RxCUI, etc.), cites the data sources (SEC EDGAR, RxNorm), includes citation URIs, and discloses internal cascading lookups. It also notes auto-disambiguation for company inputs, giving more transparency than typical safe read tools.

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

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

The description is moderately long but well-organized: starts with user-facing example queries, then states the core purpose and usage guidance, followed by SUPPORTED TYPES with detailed sub-bullets. Every sentence adds value; it could be slightly leaner, but the structure makes 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?

For a tool with no output schema, the description thoroughly explains what to expect from each type, including return fields and citation URIs. It covers when to use it, accepted inputs, and internal behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'value'. The description further enriches them by clarifying what types exist ('company', 'drug'), what input formats are accepted (ticker, CIK, name; brand/generic), and what each type returns. This goes well beyond the schema's brief enum and string 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 uses a specific verb ('resolve') and resource (entity name to canonical identifier), clearly stating the tool's function with illustrative queries ('What's the ticker for…' / 'find the CIK for…'). It distinguishes itself from siblings by noting it returns official identifiers that other tools require, which is unique relative to tools like entity_profile or compare_entities.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID' and mentions it replaces 2-3 manual lookups. It does not explicitly list alternative tools or state exclusions, but the contextual direction is clear and practical.

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

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

The description reveals the probing mechanism (with ai_visibility_check), ranking by score, and return of ranked list with score, confidence, and signal density. This adds process detail beyond the annotations, which already indicate read-only, open-world, and idempotent 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 four compact sentences, each earning its place: main action, process, use case, and return value. It is front-loaded with 'Compare AI visibility' and avoids unnecessary fluff.

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

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

The description explains what the tool does, when to use it, how it works, and what it returns. Given the detailed schema and annotations, this is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents all parameters (including the 'entities' array semantics). The description adds only a light paraphrase ('your brand + N competitors') without new details, so it doesn't exceed the baseline.

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

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

The description uses specific language: 'Compare AI visibility across multiple entities side-by-side' and explains it probes each entity, ranks by score, and surfaces recognition levels. This clearly distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a clear use case ('competitive AI-marketing audits') with an example query ('does Claude know about us as well as our competitors?') and implies the alternative of using ai_visibility_check for a single entity. It doesn't explicitly name alternatives or when not to use, so it's not 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 disclosing graceful degradation on partial failures, the 5-30s latency for first bundlephobia measurement, and the sources_failed field behavior. It also clarifies the NPM-only limitation. No contradiction with 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 is dense but well-organized, front-loading the core purpose before diving into sources, usage, return values, and limitations. Every sentence provides useful information, though the length is substantial; still concise relative to the tool's complexity.

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

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

Given the tool's complexity, no output schema, and multiple data sources, the description fully covers the return structure (summary block fields, advisories, links, alternatives), usage boundaries, and failure behavior. It gives an agent everything needed to invoke and interpret the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not significantly add parameter semantics beyond the schema; it reiterates that version defaults to latest, which is already in the schema. However, it does provide context on how parameters relate to the overall output.

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: a composite dependency evaluation check for npm packages, combining deps.dev and bundlephobia data. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes itself from siblings by focusing on package adoption decisions.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clarifies when NOT to use it (non-npm ecosystems) and directs users to deps.dev:version directly for those cases.

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

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

Annotations already declare readOnly/openWorld/idempotent/flags. The description adds behavioral context by naming the return fields and the URL's purpose, which is helpful beyond the structured annotations. No contradictions.

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

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

Two sentences, front-loaded purpose, then return format and chaining. Every word contributes value; no filler or redundancy.

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

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

Despite lacking an output schema, the description fully covers the return contract (fields and URL) and the downstream usage with sibling tools. It is complete for a search tool with simple parameters and well-behaved annotations.

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

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

The input schema already has 100% parameter descriptions for query, limit, and org_id. The description adds no new parameter semantics beyond restating keyword search and the default Washington County GIS org.

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 Washington County GIS open geospatial datasets by keyword, with specific examples (parcels, addresses, zoning). It distinguishes itself from sibling tools by describing the return payload (dataset metadata + Feature Service URL) that feeds into query_layer/layer_info.

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

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

It provides clear chaining guidance: 'pass that url to query_layer / layer_info' shows exactly how this tool fits into a workflow. It does not enumerate exclusions or alternatives like search_within, but the integration hint is strong and practical.

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

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

Beyond the read-only/idempotent annotations, the description discloses rich behavioral details: the embedding and similarity mechanism (BGE-base-en, cosine, 500-char windows), output characteristics (offsets, similarity scores), and edge-case handling (200K char cap with truncation flagging). This is substantial context that annotations alone do not 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 front-loaded with the core action, then systematically covers usage context, integration with a sibling tool, and technical implementation details. Every sentence adds distinct value with no filler, achieving a high information density.

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

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

Since there is no output schema, the description adequately explains return values (top-N passages, offsets, similarity scores) and edge-case behavior (truncation flag). It gives enough detail for an agent to select and invoke the tool correctly without missing critical 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 coverage is 100% for all three parameters, with each already having a description. The tool description reinforces this by providing examples (e.g., query examples) and usage context, but it does not add fundamentally new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record,' and clearly states the action (return top-N passages with offsets and scores). It explicitly distinguishes itself from siblings by positioning as a tool for already-fetched text and naming ask_pipeworx_grounded as the pairing alternative.

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 when-to-use: 'Use when the record is too big to cram into the prompt,' and provides a clear workflow with an alternative tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is direct guidance for when to choose 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?

Goes far beyond the annotations by detailing account requirements, delivery channel behaviors (email/sms/webhook), phone verification, SMS caps, webhook signing secret returned once, and auto-disable after 10 failures. These are critical behavioral traits not captured in annotations or schema.

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

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

The description is dense and front-loaded with the core purpose, but it is a single long paragraph with many semicolons and details. It earns its length by covering types and delivery, though it could be slightly restructured for readability. Still efficient overall.

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 three params, nested objects, and multiple subscription types, the description is remarkably complete. It covers return value, auth requirements, delivery options, and constraints. Without an output schema, it explains what the user gets (subscription id). No major gaps.

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

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

Even with 100% schema coverage, the description adds significant meaning with concrete examples for each type (e.g., sec_8k items:["5.02"] = officer change, polymarket_edge {topic:"fed"}) and delivery constraints (verified phone, 10/day cap, webhook HMAC details). This goes beyond the schema's 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 clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This identifies the specific verb (create), resource (subscription), and immediate outcome. It also lists supported subscription types, distinguishing it from sibling tools like unsubscribe and list_subscriptions.

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 context on when to use the tool (for persistent monitoring) and prerequisites (requires Pipeworx OAuth account; anonymous/BYO cannot persist). It does not explicitly contrast with alternatives like recent_alerts or query tools, but the subscription nature implies its niche. Clear context, though exclusions are not stated.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that the tool returns 'category-bucketed example questions' with 'the exact tool + argument shape' drawn from a live catalog. It also explains behavior when called with no arguments versus with a topic, and mentions the focus areas. This provides rich behavioral context not captured in annotations.

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

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

The description is long (~200 words) but front-loaded with example questions and structured with clear sections. Every sentence contributes useful information, including when to use, what to expect, and how to call. It could be slightly more concise, but the length is justified by the explanatory value.

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

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

The tool is simple (0 required parameters, no output schema), so the description fully covers its behavior: what it returns, how to call it, and when to use it. It explains the output format (category-bucketed questions with tool + argument shape) without needing an output schema. No significant gaps remain.

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

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

The schema already covers the `topic` parameter with its possible values, so the baseline is 3. The description adds value by explaining the default behavior when omitted ('full spread') and provides concrete examples of topic values ('finance', 'pharma', 'betting'). This goes beyond simply restating 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 as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the verb (suggest questions) and resource (Pipeworx capabilities), and distinguishes it from sibling tools like ask_pipeworx and discover_tools by explicitly naming them as meta-tools to learn about. The example queries make the scope concrete.

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 direction: '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 how to invoke with or without the `topic` parameter, and lists example topics. This clearly tells the agent when to choose this tool over 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?

Beyond the annotations (non-read-only, idempotent, non-destructive), the description adds meaningful behavioral context: ownership is enforced, and the row is deactivated rather than deleted, preserving historical events via recent_alerts. This complements the annotations and clarifies the side effects of the operation.

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 long, front-loading the core action and then adding a crucial caveat about ownership and deactivation. Every sentence carries necessary information, 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?

Given that this is a simple single-parameter tool with no output schema and robust annotations, the description covers the essential aspects: the operation, ownership constraint, and state change. It does not address edge cases like invalid IDs or return values, but these are not critical for such a straightforward 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 input schema already provides a thorough description of the 'id' parameter (UUID returned by subscribe) with 100% coverage. The tool description does not add any additional parameter semantics beyond referring to 'id', so it remains at the baseline for schema-heavy coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and identifies the resource (subscription). It distinguishes this tool from siblings like subscribe and list_subscriptions by mentioning ownership enforcement and the deactivation (not deletion) behavior, making its unique purpose unambiguous.

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

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

The description implies the primary use case (canceling a subscription) but does not explicitly state when to use this tool versus alternatives or when not to use it. The ownership note ('you can only cancel your own subscriptions') provides some context, but there is no explicit comparison with sibling tools or exclusion conditions.

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 substantive context: the SEC EDGAR fast path for financial claims, the grounded pipeline fallback, the exact verdict list, and the inclusion of citations and reasoning. It also notes that the tool internally replaces multiple sequential calls, which is useful behavioral insight.

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

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

The description is dense but efficient; it leads with trigger phrases and purpose, then covers routing logic, output format, and the composite benefit. Each sentence contributes new information, with no redundancy or filler. The structure logically flows from usage to internal behavior to outcomes.

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

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

Given the tool's complexity and the fact that there is no output schema, the description covers all necessary aspects: what it does, when to use it, how it processes different claim types, what it returns, and why it's advantageous. An agent can confidently select and invoke this tool based on the description alone.

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

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

The input schema covers both parameters with descriptions, and the description further enriches tolerance_pct by explaining how it overrides the claim-implied tolerance, recommends usage for hallucination detection, and clarifies the default cap. This goes well beyond the schema to guide effective parameter use.

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 natural-language claim verification, with a specific verb ('verify') and resource ('claims against authoritative sources'). It includes multiple example trigger phrases and explicitly names the verdict types, distinguishing it from general Q&A sibling tools like ask_pipeworx 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 provides an explicit when-to-use rule: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives detailed routing guidance for financial vs. non-financial claims. However, it does not explicitly define when not to use the tool or name direct alternatives, leaving a small gap.

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