Arcgis Maricopa

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations: it reveals cost implications (BYO Anthropic key, paid directly), default model choice (Workers AI Llama-3.3-70b free), and the structure of the response (per-model score, confidence, signals, raw_response plus combined view). This goes beyond the baseline and enriches the agent's understanding.

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

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

The description is compact and front-loaded: it starts with the core purpose, then covers default behavior, output format, and use cases in a few sentences. Every sentence contributes essential information, with no redundancy or fluff. It is highly efficient while still being comprehensive.

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

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

There is no output schema, but the description explicitly describes the return format (per-model {score, confidence, signals, raw_response} plus a combined view), which addresses that gap. It also provides enough context for typical use cases and parameter interactions. Minor omissions like error handling or rate limits are not critical for this kind of read-only probe tool, so it earns a 4.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful relationships: it explains that `_apiKey` is only needed when 'anthropic' is in `models` and that the default model is free. It also clarifies the `context` parameter's purpose ('helps disambiguate common names'), which adds value beyond the raw 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 action ('Probe one or more LLMs') and the resource ('what they know about a business / brand / product / topic') while specifying the output (visibility score 0-100 per model). It distinguishes itself from siblings by focusing on LLM visibility scoring, which is a unique capability 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 clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional Anthropic model (by passing `_apiKey`). However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds valuable behavioral context beyond this: it routes to 5,521 tools, fills arguments, returns structured answers with citation URIs, works on every tier, and can route to live news. This goes beyond the baseline but doesn't disclose failure modes or rate limits, so a 4 is appropriate.

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

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

The description is longer than average but every sentence serves a purpose, and it is front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. It is well-structured with examples and alternatives. There is slight redundancy (the 'even if web search could also answer it' phrase repeats the opening preference), preventing a 5.

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

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

Despite having no output schema, the description states what the return value looks like: 'structured answer with stable pipeworx:// citation URIs.' It also covers use cases, examples, and explicitly contrasts with relevant siblings. For a read-only query tool with strong annotations, this is complete enough.

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 being aliases for the single 'question' parameter, fully described in the schema. The description does not add parameter-level semantics beyond what the schema already provides, but it does give many example questions in the body text. With high schema coverage, the baseline of 3 is correct.

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

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

The description explicitly states what the tool does: 'Routes the question to the right one of 5,521 tools... returns the structured answer with stable pipeworx:// citation URIs.' It clearly identifies the action (ask/routing), the resource (Pipeworx), and differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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 extensive when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about...', 'Use whenever the user asks...', and 'START HERE for most questions'. It also explicitly states when to use alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is a clear when/when-not/alternatives structure.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the experimental nature, the possibility of live candidate routing improvements, and that no candidate is currently active. It also clarifies the tool does not fall back to anything, being a full working router.

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 tight and front-loaded, immediately identifying the tool as a beta variant. Every sentence adds necessary context—identity, current state, usage instruction, and experimental purpose—without redundancy.

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

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

Given the tool's complexity as a router with thousands of tools and no output schema, the description covers its purpose, relationship to stable ask_pipeworx, current behavior, and evaluation role. It references the stable sibling for further details, making it sufficient.

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

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

The schema fully covers all parameters with descriptions for the question field and each alias (100% coverage). The description itself adds no parameter-specific meaning, so it relies on the schema, which already 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 identifies this as the beta version of ask_pipeworx, the same universal router with 5,521 tools, while distinguishing it from the stable sibling via its experimental routing improvements. The scope and current behavior are explicitly stated.

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 this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it currently matches the stable router and that results are compared against it, making the experimental context clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavior: same routing as ask_pipeworx, exact return shape, refusal reasons, and the cost of one extra LLM call. It also clarifies that the answer is extracted 'using ONLY what the tool result contains,' which meaningfully extends the annotation information.

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 concept ('Hallucination-resistant answer mode'), then efficiently covers routing, return format, refusal behavior, use cases, and cost tradeoff. Every sentence adds distinct value, and the structure moves from purpose to mechanics to usage guidance, making it easy to scan.

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

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

Despite lacking an output schema, the description fully documents success and failure return shapes, including all refusal reasons. It also explains the relationship to ask_pipeworx and when the extra cost is justified. For a complex tool with routing and grounding logic, this is highly complete.

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

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

Schema description coverage is 100%, and all parameters are aliases for the same natural-language question. The description reinforces this by referring to 'fetches the data' and 'extracts the answer,' but it doesn't add meaning beyond the schema's clear alias descriptions. Baseline 3 is appropriate because the schema already handles parameter clarity.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and specifies that it routes like ask_pipeworx but extracts answers using only tool results. This distinguishes it from sibling tools like ask_pipeworx and ask_pipeworx_beta by emphasizing grounded, evidence-based answers with explicit refusals.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and provides a preference: 'prefer ask_pipeworx for casual lookups.'

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

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

Beyond the readOnly/idempotent annotations, the description extensively discloses behavioral traits: resolver confidence levels that short-circuit analysis, closed-market status with fan-out suppression, illiquid wide-spread warnings, GDELT fallback with retry fields, and cancellation-rule risk parsing (e.g., refund_50_50 with EV impact). This goes far beyond the annotations and arms the agent with critical safety context.

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

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

The description is long but meticulously structured with capitalized section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) and front-loads the core purpose and usage in the opening sentences. Every section provides distinct, useful detail for a complex tool; while dense, there is little filler and the organization aids parsing.

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

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

With no output schema, the description must explain return values and behaviors, and it does comprehensively: result.market fields, result.analysis model probability/edge and 24h-move warning, result.evidence keying, resolver match fields and alternatives, parent_event extractor, news fallback fields, status codes, and cancellation-rule handling. It covers normal operation and numerous edge cases, making it effectively 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 input schema already covers all three parameters with clear descriptions (market accepts slug/URL/question text, depth quick vs thorough, include_raw default and behavior). The description strengthens the depth parameter with concrete fan-out examples (e.g., BTC bet → coingecko + fred + gdelt+gnews), but adds no new parameter-level semantics beyond what the schema provides. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a clear verb+resource statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then specifies accepted inputs (slug, URL, question text) and distinct use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), making the tool's purpose unmistakable and differentiating it from sibling Polymarket 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 usage scenarios ('Use for...') and rich operational guidance: always inspect resolver confidence before trusting analysis, check cancellation rules before sizing bets, and expect blocking statuses for low-confidence or closed markets. It does not explicitly name alternative tools for 'when not to use', but the positive guidance and edge-case handling are strong 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?

Beyond the read-only/idempotent annotations, the description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URI output. This significantly enhances understanding of what the tool does internally.

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 densely packed with useful information—trigger phrases, preference rule, data details, and return format—but the all-caps 'ALWAYS PREFER' and multiple example phrases make it slightly verbose. Still, every sentence earns its place, and it is 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?

With only two parameters and no output schema, the description fully covers what the agent needs: it states data sources, metrics, sorting behavior, and return format (paired data + citation URIs). For a tool of this complexity, it leaves no critical 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?

The schema already describes both parameters with 100% coverage, but the description adds valuable semantics: type='company' maps to 10-K financials, type='drug' maps to FAERS counts, and values must be tickers/CIKs vs drug names. It also clarifies the 2-5 limit with examples, going beyond the schema.

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

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

The description clearly identifies the tool as a side-by-side comparison of 2–5 entities in one parallel call, with explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups, making its purpose and scope unmistakable.

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

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

It explicitly instructs the agent to prefer this tool over sequential single-pack lookups when comparing entities and provides concrete query examples that signal when to use it. This gives actionable usage guidance with a clear alternative.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral context: account requirements and pricing, latency expectations (15-60s, up to 90s), explicit gap handling (never invented), contradictions[] for standard/thorough, semantic excerpting of large records, citation_uri only when fetchable, and depth-specific iteration behavior. This far exceeds what annotations provide.

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

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

The description is long but dense with valuable information. It is front-loaded with the account requirement and key differentiators. Every sentence adds substance, but it could be slightly trimmed without losing essential guidance.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It covers return packet fields (verbatim evidence, confidence, source, fetched_at, citations, gaps, contradictions, hop), explains limitations, gives latency estimates, and describes depth-specific behavior. No critical operational detail appears missing.

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

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

Schema description coverage is 100% for both parameters (question and depth). The tool description adds example questions and clarifies the value of depth options, but these are largely embellishments of the schema. Since the schema already documents parameter behavior, 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: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources ... in ONE call', with a specific verb and resource. It distinguishes itself from siblings by explicitly noting it is 'NOT open-web search' and describing its decomposition into facets and parallel routing to 5,521 tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Also describes best-case scenarios for deep_research (broad/multi-part questions over structured data) and depth-level behavior.

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

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

Annotations already mark the tool read-only and idempotent. The description adds behavioral value by disclosing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' 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 two sentences, front-loaded with purpose, and each clause adds useful information (domains covered, return format, no-lookup needed, first-call recommendation). While slightly long, 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?

Despite having no output schema, the description fully specifies what the tool returns (top-N tools with schemas and examples) and when to invoke it. Given its meta-search role and clear behavioral contract, the description is complete for an agent to select and invoke it correctly.

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

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

The input schema provides full descriptions for all 6 parameters, including alias relationships. The description does not add parameter-specific semantics beyond what the schema already covers, 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It enumerates many domains and explicitly distinguishes itself from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description states when to use it ('when you need to browse, search, look up, or discover what tools exist') and provides an explicit directive to use it first when many tools are available. It also contrasts with getting 'just one answer,' implying specialized tools are for direct queries.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it fans out across multiple sources in 'ONE parallel call', returns specific enumerated fields, and discloses the USPTO patents API soft-fail until reactivated. This goes beyond annotations and helps set 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 a single dense paragraph, but it is front-loaded with example queries and every sentence contributes value. It could be more structured with bullet points, but the length is justified by the tool's complexity and the need to list return fields.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does this comprehensively by listing CIK, filings, fundamentals, patents, news mentions, and LEI, plus noting the patents limitation and the 'up to 5' filings detail. It also covers input constraints and alternatives, making it complete for a complex fan-out 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 covers 100% of parameters with descriptions, including the ticker/CIK value and the 'names not supported' caveat. The description reinforces this with examples but does not add semantic detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses specific verbs like 'tell me about', 'research', and 'brief me on' and clearly states it produces a 'full cross-source profile of a US public company'. It distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups for holistic views, and it references resolve_entity for name-only inputs.

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: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view'. It excludes name-based queries ('names not supported') and directs users to resolve_entity first, giving a clear alternative for that case.

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 what gets destroyed (a previously stored memory) and specific use cases for deletion (stale context, completed task, sensitive data). This goes beyond the annotations by explaining the rationale for deletion.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value. It avoids redundancy with the schema and annotations, making it compact and effective.

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

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

For a simple one-parameter tool with full schema coverage and annotations for destructive and idempotent behavior, the description fully covers when and why to use it. No output schema exists, but the tool's behavior is straightforward, so no further explanation is needed.

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 the parameter (key) with a clear description, so the baseline is 3. The description adds little beyond 'by key' and an example, but it does reinforce the parameter's role in the action. No additional syntax or constraints are 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 clearly states the verb 'Delete' and the resource 'previously stored memory by key', which precisely defines the tool's action. It also distinguishes from siblings by mentioning pairing with 'remember and recall', making its role in the memory workflow clear.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), helping the agent decide between 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?

The description adds value beyond annotations by explaining the fetch-extract-emit process and specifying the output format (a single text blob). It also notes the target location (site-root/llms.txt). Annotations already cover safety, and the description does not contradict 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 two sentences plus a use-case list, with the primary action front-loaded. Each sentence adds distinct information—function, process, output, and scenarios—without redundancy.

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

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

For a two-parameter tool with no output schema, the description sufficiently covers purpose, process, output, and usage contexts. The annotations provide safety clues, so the tool is fully contextualized.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description reinforces the URL parameter's role ('for any URL') and mentions 'key links' which relates to max_links, but doesn't add substantial new semantics beyond the schema.

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

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

The description clearly specifies the tool's function: generating a production-ready llms.txt file for any URL. It distinguishes itself from sibling tools by emphasizing the concrete output (llms.txt file) rather than just checking AI presence. The explicit use cases further clarify scope.

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

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

The 'Useful for' list provides three concrete scenarios: obtaining a client's site indexed, drafting for your own project, and auditing competitors. While it doesn't name alternative tools explicitly, the scenarios effectively communicate when this tool is appropriate given sibling tools like scan_competitor_ai_presence.

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

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

Annotations declare read-only/idempotent, so the description adds value by listing what is retrieved (fields, geometry type, record count, capabilities). It doesn't contradict annotations and provides useful behavioral context 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?

A single sentence that is front-loaded with the action and resource, then lists specific output items. No wasted words, perfectly structured.

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

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

For a simple one-parameter tool with no output schema, the description covers the main return components and input method. Minor gaps like potential URL validation or approximate record counts are not critical for an initial understanding.

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 parameter description including an example. The tool description only says 'by url', adding no extra semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets an ArcGIS layer's schema, specifying exact outputs (fields, geometry type, record count, capabilities). The verb 'Get' and resource are specific, and it's easily distinguishable from sibling tools like query_layer.

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

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

The description implies usage when you need schema/metadata for a layer, but it doesn't explicitly mention when not to use it or mention alternatives like query_layer. No exclusions or alternatives are stated, relying on 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 declare readOnly, idempotent, and openWorld hints. The description adds value by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying that only active subscriptions are listed by default. This enriches the agent's understanding beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, followed by return fields and a usage hint. Every word earns its place; there is no redundant information.

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

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

For a simple read-only list tool with one optional parameter, comprehensive annotations, and a fully described schema, the description is complete. It covers what the tool does, what it returns, and why an agent would use it, without needing to explain return formats further.

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 single optional parameter include_inactive is fully described in the schema with a clear default and behavior. The description does not add additional parameter semantics, but with 100% schema coverage, 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 action (list), resource (subscriptions), and scope (caller's active). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing active subscriptions, and it enumerates the returned 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 gives explicit context for when to use the tool: to review current monitoring before adding more, or to find an id to cancel. While it doesn't name alternatives like subscribe/unsubscribe directly, the intended usage is clear and the sibling list provides the tool 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?

Discloses rate limiting (5 per identifier per day), cost (free, no quota), the claim_token workflow for anonymous reporting, and the scope restriction to Pipeworx-served tools. Since annotations are all false and provide no behavioral hints, the description fully carries the burden and does so thoroughly.

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

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

Every sentence adds value: purpose, use cases, exclusions, formatting guidance, claim_token workflow, rate limit, and cost. The description is dense but appropriately sized for the tool's complexity, with the main purpose front-loaded.

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

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

Covers when to use, when not to use, what to provide, what to expect (claim_token and follow-up), and operational limits. With no output schema, the description sufficiently explains the return token mechanism. The tool's complexity is well handled.

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 all 4 parameters with detailed descriptions (100% coverage). The description mentions the claim_token workflow but adds little beyond the schema's own explanation, so it does not significantly augment parameter understanding beyond the baseline.

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

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

The description opens with a clear imperative ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates the feedback categories (bug, feature/data_gap, praise). It explicitly scopes the tool to this Pipeworx connection, distinguishing it from sibling tools and 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 'Use when' triggers are provided for bugs, features/data gaps, and praise. The description also gives a clear exclusion: tools from other MCP servers should be reported elsewhere. Additional guidance covers how to frame feedback (in terms of Pipeworx tools/packs) and how to follow up with claim_token.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses aggregation and caching behavior beyond the annotation 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 front-loaded with a clear one-liner, followed by a structured list of three use cases and a final technical note. While longer than minimal, every sentence adds value; the structure makes it scannable. It's not as concise as get_calls but well-organized.

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

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

For a simple read-only tool with one parameter and no output schema, the description adequately covers output ('top tools, top packs, total call volume'), data shape ('(pack, tool, count)'), and caching behavior. It doesn't specify exact response formatting, but the absence of an output schema lowers the burden.

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 single 'window' parameter at 100% including enum values and descriptions of behavior. The tool description only mentions the window in passing and does not add new semantics beyond the schema, 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 opens with 'What other AI agents are calling on Pipeworx right now' and explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource with clear scope, and it differentiates itself from sibling tools like 'discover_tools' by focusing on real-time aggregated call volume.

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

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

The description provides three explicit use cases (hot data sources, canonical tool confirmation, alignment with agent needs), giving clear context for when to use it. However, it does not name alternative tools or state when not to use it, so it falls short of full 5.

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

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

The description is extraordinarily transparent about behavior beyond annotations. It discloses the Jaccard similarity threshold (≥0.30), partition filter rules (>20% placeholder fraction returns null), fill check mechanics against live CLOB depth, and the interpretation of realizable_edge_pp ≤ 0 (do not trade). This far exceeds the readOnlyHint/openWorldHint/idempotentHint annotations by adding critical domain logic.

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 it is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and argument patterns. Every sentence adds substantive value (thresholds, examples, output details), making it dense rather than wasteful. However, it is not as minimal as the top-tier example; a few details could be streamlined without loss.

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

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

Despite having no output schema, the description fully compensates by describing the response shape ('opportunities[] with gap_pp, suggested_trade, reasoning...') and including edge cases like thin_legs and skipped_low_similarity. It also contextualizes when to combine with polymarket_fill_risk. For a complex tool with 2 optional parameters, this is complete.

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

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

Schema coverage is 100% for both parameters, and the description goes far beyond the schema. It provides examples of valid values ('fed-decision-may-2026', 'when-will-bitcoin-hit-150k'), explains full Polymarket URLs are accepted, and details the distinct behavior for each mode (event vs topic), including what types of insights each yields. This enriches both parameters considerably.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools by detailing unique mechanisms (monotonicity, partition-check, trending scan) and explicitly names alternative tools for different tasks (e.g., polymarket_fill_risk for sizing).

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 mode selection: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' However, it does not fully delineate when not to use this tool versus other edge-finding siblings like polymarket_edges or polymarket_kalshi_spread, so it falls short of a perfect 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 safe read-only/idempotent behavior, but the description adds extensive behavioral detail: model families, net edge calculations, Kelly caps, slippage assumptions, the 24h-move warning, and caching at the KV level. This far exceeds what annotations alone convey.

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

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

The description is very long but densely packed with essential operational details (response shape, diagnostic keys, edge cases). It has a clear structure (segments, knobs, response top-level), though it could be trimmed without losing core meaning; the per-sport α values and exact gate relaxations are arguably TMI.

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

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

Given the tool's complexity (9 params, 3 model families, nested response), the description covers purpose, output structure, diagnostics, caching, and edge-case warnings. There's no output schema, so the description's breakdown of by_segment and _diagnostics fully compensates.

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 enriches several knobs with behavioral implications — e.g., min_partition_leg_kelly exists because partition arbs always return kelly_fraction_half=0 at the parent level, and slippage_pp is contextualized with Polymarket's zero-fee/tight-spread environment. This adds meaning 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 a specific verb ('Scan') and resource ('top Polymarket markets'), and clearly distinguishes from siblings by mentioning 'Pipeworx data disagrees with market price' — a unique signal. It also names the three output segments, making the tool's scope unmistakable.

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

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

It explicitly states the intended use case ('what should I bet on today') and even notes when the tool is not useful ('Fed bets surface here, excluded from ranking... unreliable'). However, it doesn't explicitly name sibling tools as alternatives, so it misses a direct when-not-to-use comparison.

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

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

The description adds extensive behavioral context beyond the annotations: snapshots are written on cache-miss, gaps mean no scan, history is bounded by a 60-day TTL, decay is computed from daily closes not intraday, and edge_pp_net is signed by trade direction with negative values representing SELL YES. These details significantly enhance an agent's understanding of data freshness and interpretation.

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

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

The description is long but dense with necessary information about parameters, response structure, and limitations. It is organized with 'Args:' and 'RESPONSE:' labels, making it scannable despite the length. Every sentence contributes value, though it could benefit from bullet points for even clearer separation of concepts.

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 thoroughly explains the return structure: tracked[] with time-series and trends, expired[] with lifespan, and snapshot_dates[] with caveats about gaps. It also covers edge cases like missing snapshots and history depth limits, making the description complete for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the default for days and window and adds the phrase 'snapshot family' for window, but this adds limited meaning beyond what the schema already provides. No additional parameter semantics are needed given the thorough 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 defines the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question: 'how long has this edge existed and is it shrinking?' It also contrasts fresh vs. old wide edges, which distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides clear context: 'a fresh wide edge and a 3-week-old wide edge are different trades', implying the tool is used to assess edge durability before trading. It does not explicitly name alternatives or exclusion conditions, but the focus on snapshot persistence over time makes the intended use clear relative to other Polymarket 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, all consistent with the description. The description adds significant behavioral context, such as walking the order-book ladder, returning verdict categories (clean|degraded|cannot_fill), and warning about forced directional risk and partial fills.

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 clear sections for SINGLE-MARKET and BASKET modes. Every sentence adds informative value given the tool's complexity, though a slightly tighter structure could improve readability.

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

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

With no output schema, the description fully enumerates all return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, forced_directional_risk) and explains edge cases and risk profiles. It also covers mode-specific behavior, making it a complete reference for the agent.

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

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

Although the schema covers 100% of parameters, the description adds crucial semantics: it explains the two modes (single-market vs basket), how size_usd is interpreted differently in each mode, and the default auto behavior for side in basket mode. This goes beyond the schema's basic 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 identifies the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which is a specific verb-resource combination. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk and slippage.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing the risk of partial basket fills and unhedged directional positions.

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

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

Annotations already mark it read-only/idempotent; the description goes well beyond by detailing the matching algorithm's failure modes (skipped_cross_type, skipped_cross_subtype), the two compatibility_warning scenarios, and temporal alignment impact. It honestly discloses that most macro shortcuts currently return warnings, which is valuable behavioral context.

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

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

The description is information-dense and structured into modes/response/safety sections, but it runs long and repeats the 'tool says so' caveat. Still, every clause adds operational detail, so it's efficient 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?

With no output schema, the description covers response shape (raw probabilities, top_spreads_pp), warning fields, and skipped-leg semantics. It leaves little ambiguity about when results are meaningful, making it complete for a niche tool.

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

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

The schema gives each parameter a name and short description, but the tool description adds the conceptual model: topic vs. explicit override, and the exact list of ten macro shortcuts. It explains how kalshi_event_ticker overrides the topic side and polymarket_event_slug overrides the other, making param interplay clear.

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 precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' naming the two specific venues and the metric. It states two operating modes and explicitly warns about non-equivalent bet shapes, distinguishing it from generic arbitrage 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?

While it never names sibling tools like polymarket_arbitrage, it gives clear conditional guidance: use the pre-mapped topics when the question resolves on both venues, use explicit tickers for custom pairings, and avoid interpreting spreads when compatibility_warning fires or temporal_alignment.aligned is false. The caveat that pre-mapped topics are not automatically tradeable further instructs the agent on correct interpretation.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds useful behavioral context, such as returning attribute rows and geometry, and the sampling trick. It does not contradict annotations and provides value beyond the structured fields.

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 concise sentences, front-loaded with the main action and resource, then listing parameters and a helpful tip. Every sentence earns its place with no wasted words.

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

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

Given 6 parameters, 100% schema coverage, no output schema, and rich annotations, the description sufficiently covers what the tool does, where URLs come from, and how to sample. It could detail return format further, but the note about returning attributes and geometry plus schema-covered parameters is enough for a list/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 coverage is 100%, so the baseline is 3. The description summarizes key parameters (where, out_fields, order_by, limit, offset) and mentions 'SQL-like', which adds slight nuance, but it largely mirrors the schema's parameter descriptions. It does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, with a specific verb ('Query') and resource. It also lists the main parameters, making it distinct from sibling tools like 'layer_info' or 'search_datasets'. The mention of 'from search_datasets' establishes the data source and workflow.

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

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

The description provides clear context: it is used to query layers obtained from 'search_datasets', and gives a practical sampling tip ('Use where="1=1" + out_fields="*" to sample.'). It does not explicitly mention when not to use or name alternative tools, but the context is strong enough to guide the agent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: scoping ('Scoped to your identifier...') and the list-all-keys behavior when key is omitted. It does not contradict any annotations, and these extras help the agent understand visibility and 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?

Three sentences, each purposeful. It opens with the core action, gives practical examples, and closes with scoping and sibling relationships. No wasted words or redundant restatement of 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?

For a simple, read-only, single-parameter tool with full schema coverage and rich annotations, the description covers purpose, use case, scoping, and alternatives. No critical gaps 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 coverage is 100% for the single parameter 'key', and its description already states 'Memory key to retrieve (omit to list all keys)'. The tool description reinforces this but adds no substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states 'Retrieve a value previously saved via remember, or list all saved keys' — a specific verb and resource. It distinguishes from siblings by explicitly naming remember and forget as paired tools. No ambiguity about its function.

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

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

It provides an explicit use case: 'Use to look up context the agent stored earlier' with concrete examples like ticker, address, and research notes. It also tells when to use alternatives: 'Pair with remember to save, forget to delete.' This gives clear when-to-use guidance and names sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context by explaining the mark_read behavior ('flag returned events read so the next call only shows newer ones') and mentioning that polls work fine. This clarifies the only mutable aspect without contradicting the readOnlyHint because it's opt-in.

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

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

The description is three sentences, front-loaded with the core purpose, then quickly covers return payload, filtering, mark_read, polling, and an alternative URL. Every sentence adds 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?

With 5 optional parameters, no output schema, and moderate complexity, the description covers the key aspects: what is returned (source, citation_uri, raw payload), filtering by type and time, the mark_read side effect, polling suitability, and an alternative access point. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already fully described in the schema. The description adds beyond that by giving a concrete example for type ('sec_8k'), explaining the 'since' filter as an ISO timestamp comparison, and describing the effect of mark_read. This enriches the schema's dry 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+resource: 'Pull fired events from your subscription feed.' It clearly states the tool returns recent alerts written to a persisted feed, and distinguishes itself from sibling tools like list_subscriptions or recent_changes by focusing on alert events with specific metadata (source, citation_uri, raw payload).

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

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

The description provides clear context: it's for polling alerts from a subscription feed, and even mentions an alternative access method for scripts/dashboards (the direct JSON URL). It does not explicitly compare against sibling tools or state when not to use it, but the polling guidance and alternative URL offer practical usage 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?

Goes beyond the read-only and idempotent annotations by disclosing multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback triggers (rate limited/5xx), soft-failure due to PatentsView API sunset, and the exact return shape (changes[], total_changes, citation URIs). This gives the agent full visibility into side effects and output 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?

While the description is longer than average, each segment serves a distinct purpose: user examples, source breakdown, parameter clarification, output format, and alternative tool. The organization into clauses with clear logical flow means no sentence is wasted, justifying the length.

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

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

Despite having no output schema, the description fully covers invocation, input formats, output structure, failure modes, and alternatives. It provides all the information an agent needs to select and correctly invoke the tool, and to interpret the result, making it contextually 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 already describes all 3 parameters at 100% coverage. The description adds value by providing concrete `since` format examples ('7d', '30d', '3m', '1y') and typical usage guidance ('30d' or '1m'). This elevates it above baseline without fully re-explaining each parameter.

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

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

The description clearly identifies the tool as a 'change feed for a company' returning recent filings, news, and patents. It opens with diverse user query examples and explicitly distinguishes itself from sibling entity_profile ('Use entity_profile instead when you want the static 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?

Provides explicit when-to-use cues ('What's new with X', 'latest on Y') and an explicit alternative (entity_profile) for static data. Also gives concrete parameter guidance ('Use "30d" or "1m" for typical monitoring') and explains fallback behavior between GDELT and GNews.

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 (idempotent=true, destructive=false), the description adds valuable behavioral context: key-value scoping by identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. These details are not present in the annotations and meaningfully inform agent 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 four concise sentences, each earning its place: purpose, usage scenarios, scoping/persistence, and pairing with related tools. It is front-loaded with the core action and contains no redundant or filler text.

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

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

For a simple 2-parameter write tool with no output schema, the description covers all essential aspects: what it does, when to use it, how data is scoped, retention semantics, and how it relates to recall/forget. It is fully self-contained and complete.

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

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

Schema description coverage is 100%, with both `key` and `value` having detailed descriptions and examples. The tool description reinforces the kind of content to store (ticker, address, preference) but does not add parameter-specific information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later'. It clearly distinguishes from sibling tools by explicitly pairing with 'recall' and 'forget' for retrieval and deletion, respectively.

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 concrete when-to-use scenarios ('when you discover something worth carrying forward... so you don't have to look it up again') and names the alternatives ('Pair with recall to retrieve later, forget to delete'). This gives clear usage guidance relative to sibling memory 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?

The annotations already declare the tool as read-only, idempotent, and non-destructive. Beyond this, the description adds valuable behavioral context: it discloses the output structure (ticker, CIK, RxCUI, etc.), citation URIs, auto-disambiguation behavior, and that each call cascades through multiple lookup endpoints internally. This goes well beyond the annotations and helps the agent understand the tool's 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 longer than the ideal two sentences but is well-structured: it starts with user query examples, provides the core purpose, gives explicit usage priority, and then breaks down supported types with output details. Every sentence adds value, and the structure makes it scannable. It is concise enough for the complexity it covers.

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

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

Given the two-parameter schema, no output schema, and annotations, the description covers the essential context: input formats, return values per type, citation URIs, and the cascading nature. It is complete for a tool of this complexity, though it could mention error handling or edge cases. The output schema absence is compensated by clear return descriptions.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifies input formats for each entity type, enhancing the schema. This exceeds the baseline 3 for high coverage, though not dramatically, so a 4 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: resolves user-spoken names to canonical/official identifiers required by other tools. It gives specific example queries, lists supported entity types, and uses a distinct verb-resource combination ('resolve a NAME to identifier'). This effectively distinguishes it from sibling tools by focusing on name-to-ID resolution.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and input formats, giving clear context. However, it does not explicitly state when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: it probes each entity, ranks results by score, treats the first entity as the narrative subject, and returns score, confidence, and signal density. No contradiction with annotations.

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

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

The description is three sentences with a clear structure: purpose in the first sentence, mechanism in the second, and use case plus output in the third. There is no fluff or redundancy; 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 tool with four parameters (one required) and no output schema, the description covers the operational flow (probes, ranks, surfaces), the return format (ranked list with score, confidence, signal density), and a realistic example. It is fully actionable and differentiates from sibling tools.

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 detailed descriptions for all four parameters (100% coverage), including the nuance that the first entity is the 'subject'. The description only reiterates this aspect without adding new parameter-level semantics, so the baseline of 3 applies.

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

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

The description opens with a clear action ('Compare AI visibility across multiple entities side-by-side') and specifies the resource (entities) and mechanism (probes with ai_visibility_check and ranks by score). It distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison and ranked output.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') with an example query, making it clear when to use this tool. It does not explicitly mention alternatives or when not to use it, but the context is strong enough for an agent to infer the appropriate scenario.

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 readOnly/idempotent annotations, the description discloses partial failure behavior, bundlephobia's potential 5-30s first measurement, and the sources_failed field. This gives agents a realistic model of runtime 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 long but every sentence earns its place: purpose, data sources, use cases, return summary fields, ecosystem limitation, and failure behavior. It is front-loaded with the core purpose and remains tightly packed.

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 explicitly enumerates the returned fields (is_latest, license, bundle sizes, etc.), covers ecosystem scope, and addresses edge cases like timeouts. This provides a complete operational picture for the agent.

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

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

Schema coverage is 100%, but the description adds valuable meaning: scoped packages are accepted, version defaults to latest, and the semantics of composite check are clarified. This goes beyond the schema's basic type 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 a composite check for npm packages with specific sources (deps.dev and bundlephobia) and concrete outputs. It uses a specific verb and resource, and distinguishes itself from sibling tools like deep_research or scan_competitor_ai_presence.

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

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

Explicitly provides use cases ('is X safe / popular / small') and alternatives for non-npm ecosystems (PyPI/Maven/Cargo/Go → deps.dev:version). This is exactly what an agent needs to decide when to invoke this tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds value by disclosing the return structure (name, summary, record_count, owner/org, url) and the intended downstream use, which goes beyond the annotations. It does not mention edge cases like empty results, but this is a minor omission given the strong safety 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 a single, well-structured sentence that front-loads the action and specific examples, then provides return-value details and downstream guidance. Every word earns its place; there is no fluff, and it is immediately scannable.

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

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

The tool has only three parameters (fully described in schema), full annotations, and no output schema. The description covers the search scope, return fields, and the next-step tool usage, providing complete context for an agent to select and invoke the tool correctly. Nothing essential is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds only general context ('by keyword') and does not elaborate on limit or org_id beyond what the schema provides. This matches the baseline for high schema coverage.

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

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

The description clearly states the tool's specific verb (Search), resource (Maricopa County GIS open geospatial datasets), and scope (parcels, elections, public works & planning). It also distinguishes itself from siblings by noting the output URL is intended for query_layer / layer_info, making the tool's role in the workflow explicit.

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

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

The description implies when to use this tool (to find datasets by keyword before querying layers) and explicitly names the downstream tools (query_layer / layer_info) as alternatives for further data access. It lacks explicit 'when not to use' guidance, but the context is clear for an agent.

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

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

Annotations already declare readOnlyHint and non-destructive behavior, but the description adds substantial implementation details beyond those: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagging, and the inclusion of character offsets for verification. This gives the agent valuable non-obvious context about performance and 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 front-loaded with the core purpose, then expands into usage guidance, pairing, and technical details. Every sentence carries useful information, but the technical details about embeddings and window sizes are somewhat dense and could be separated for easier scanning. Still, it is appropriately sized for the complexity.

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

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

With no output schema, the description carries the burden of explaining the return format, which it does ('passages with character offsets and similarity scores'). It also covers truncation behavior, the intended use case (large documents), and the complementary sibling tool. The description is self-contained and provides enough context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description reinforces the top-N concept and provides query examples, but it doesn't add meaning 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 opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly identifies the input (text already pulled) and output (top-N passages with offsets and similarity scores), and it distinguishes the tool from the sibling ask_pipeworx_grounded by explaining the complementary workflow.

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: 'when the record is too big to cram into the prompt.' It also mentions the paired sibling (ask_pipeworx_grounded) and how search_within fits into that workflow. However, it doesn't state explicit when-not-to-use cases or list alternative tools beyond the one named sibling, so it falls just short of a perfect 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 discloses important behavioral details beyond annotations: auth requirements (OAuth account, anonymous/BYO cannot persist), rate limits (10/day SMS cap), and delivery semantics (feed always on, email/SMS optional). It doesn't mention webhook (present in schema) or duplicate subscription behavior, but annotations (idempotent) cover idempotency.

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 a clear opening sentence, followed by requirements and examples, and then delivery channels. It is dense but every sentence adds value; there is no fluff. The information is front-loaded and well-organized for the complexity of the tool.

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

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

The description covers most aspects: purpose, return value, auth requirements, delivery options, and rate limits. It omits two of the five subscription types (patent_grant and clinical_trial) from the list, but the schema enum and parameter descriptions cover them. Since there is no output schema, stating the return value (subscription id) is important and done.

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 description adds meaning beyond the schema by providing examples and explaining the semantics of some types, e.g., 'sec_8k' as '8-K filings matching ticker + item codes' and 'polymarket_edge' as 'Polymarket↔Kalshi cross-venue mispricings'. While schema coverage is 100%, these clarifications help the agent understand the domain.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb (create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on the creation aspect. The return value (new subscription id) is also mentioned.

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

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

The description provides clear context on when to use the tool (for proactive monitoring) and states prerequisites (Pipeworx OAuth account, verified phone for SMS). It also explains delivery channels, including the always-on feed and optional email/SMS. It doesn't explicitly mention alternatives, but the context with sibling tools makes the use case clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds meaningful behavioral context beyond that: the response is category-bucketed example questions, each paired with the exact tool and argument shape, drawn from the live catalog. It also discloses the behavior of omitting vs. providing the topic parameter, which is useful and not redundant with 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 a dense, single paragraph that is front-loaded with natural user questions. Every clause contributes either return behavior, category examples, or usage guidance; there is no filler or repetition. It is slightly long, but the length is justified by the onboarding purpose and the need to convey the tool's value and calling conventions.

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 return values, and it does: it clearly states the response contains category-bucketed example questions, each with the exact tool and argument shape, drawn from the live catalog. It also covers when to use it, how to call it with no arguments or a topic, and how it relates to meta-tools. This is complete for a discoverability tool with simple parameters and strong annotations.

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

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

Schema coverage is 100% since the single optional topic parameter is fully described with its allowed values and the note to omit for a cross-category spread. The description reinforces this with examples like 'finance', 'pharma', and 'betting', and reiterates the no-argument behavior, but it adds no new semantic information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource with clear scope: it returns category-bucketed example questions showing which Pipeworx tools answer what, and explicitly positions itself as 'the onboarding entry point.' It distinguishes itself from sibling tools like ask_pipeworx (actual querying) and discover_tools (tool discovery) by focusing on what to ask and how to learn tool-calling patterns.

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

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

It gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It names specific alternatives (ask_pipeworx, entity_profile, compare_entities) and describes both the no-argument full-spread call and the topic-focused variant. This is clear when-to-use direction that goes beyond generic statements.

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=false and destructiveHint=false, and the description adds valuable context: ownership is enforced, and the row is deactivated rather than deleted, so historical events remain accessible via recent_alerts. This explains side effects beyond what annotations convey and aligns with the destructiveHint flag. 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?

Two sentences with no wasted words; the purpose is front-loaded and each clause contributes either the action, a constraint, or the side effect. This is exemplary conciseness.

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

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

For a single-parameter mutation tool with annotations covering safety, the description covers the action, ownership, and post-effect (soft delete). It even points to recent_alerts for historical data. It could hint at return behavior, but given the simplicity and existing annotations, it's 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 schema already provides 100% coverage for the id parameter with its description. The description adds a meaningful constraint by stating ownership is enforced, clarifying that only ids belonging to the caller are valid. This goes beyond the schema's basic uuid description.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource that clearly states the action. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation. The ownership enforcement adds further clarity on 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 implies use when you want to cancel a subscription, with the explicit constraint that you can only cancel your own. It references recent_alerts for post-cancellation history, but does not explicitly contrast with sibling tools like list_subscriptions or subscribe. The ownership requirement serves as a clear precondition, though alternatives are not named.

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, but the description adds valuable context: the two routing paths (SEC EDGAR versus grounded pipeline), the judgment methodology with exact percent-delta math and verbatim evidence, and the output structure (verdict, actual value with citation, reasoning). This goes well beyond the annotations.

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

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

The description is longer than average but every section earns its place: invocation examples, routing logic, output specification, and efficiency benefit. It is front-loaded with the most important info and structured logically, though it could be tightened slightly without losing value.

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

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

Despite having no output schema, the description fully explains the return values (verdict options, actual value with pipeworx:// citation, reasoning). It covers both execution paths, default behaviors, and the tool's advantage over sequential calls, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantics for both parameters: it gives concrete examples for 'claim' and explains how 'tolerance_pct' overrides implied tolerances, with default cap of 5 and suggested values for hallucination detection. This elevates it 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 clearly identifies the tool's purpose: natural-language claim verification against authoritative sources. It provides specific example phrasings and distinguishes between the financial-claims fast path and general grounded pipeline, making its scope unambiguous and differentiating it from sibling research 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 explicitly states to use the tool 'whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. However, it does not explicitly state when NOT to use it or mention specific alternative tools, so it falls just short of full explicit guidance.

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