Arcgis Carlsbad

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful context beyond that: the default model is free ('Workers AI Llama-3.3-70b (free)'), passing _apiKey has cost implications ('you pay Anthropic directly'), and it describes the return structure. It doesn't cover failure modes or rate limits, but adds enough for an agent to understand the tool's external behavior.

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

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

The description is three sentences, each earning its place: first sentence explains the core action and output, second adds default and cost behavior, third lists use cases. It is front-loaded with the most important information and avoids fluff.

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

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

Despite no output schema, the description explicitly lists the return shape: 'per-model {score, confidence, signals, raw_response} + a combined view.' With annotations covering safety and external access, and full schema coverage, the description is complete for selection and invocation. It also covers use cases and invocation details, so 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?

Schema coverage is 100%, so baseline is 3. The description adds a key semantic detail not in the schema: the default model is 'Workers AI Llama-3.3-70b (free)' and that _apiKey is for 'Anthropic' with a BYO-key cost model. It also clarifies the relationship between models and _apiKey. This goes beyond what the parameter descriptions alone provide, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb, resource, and scope, and mentions specific models and output. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it's one step below the strongest purpose clarity.

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

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

The description provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies when to pass _apiKey to probe Anthropic, and notes the free default. However, it does not mention when not to use the tool or name alternative tools, so it lacks the 'when-not' dimension.

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

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

Beyond annotations already indicating read-only, open-world, and idempotent behavior, the description discloses that it routes to 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citations, and works on every tier. It doesn't mention failure modes or rate limits, but this is not required given the annotations and the tool's aggregator nature.

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 'PREFER OVER WEB SEARCH', then organized into categories, usage triggers, examples, alternative tool guidance, and a breaking-news note. Every sentence contributes substantively without fluff, achieving high information density in a well-structured format.

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 (routing to thousands of tools) and lack of an output schema, the description adequately explains return format, usage scope, and relationships to siblings. It provides enough context for an agent to know when to choose this tool and what to expect in the answer.

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 documents all six parameters as aliases for the same 'question' field, so the baseline is 3. The description adds semantic value by listing many example questions and clarifying that any natural-language factual question is acceptable, enriching the meaning of the parameter beyond the schema text.

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

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

The description clearly states the tool routes questions to a large collection of verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from web search and names sibling tools (ask_pipeworx_grounded, deep_research) as alternatives, positioning itself as the default entry point.

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

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

Provides explicit guidance on when to use this tool vs alternatives: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and 'Step up only when needed' with specific references to grounded and deep research. Includes concrete query examples and even covers breaking-news routing.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals that candidate routing improvements may be active, that none are active now, and that results are compared against the stable router. This clarifies the experimental edge behavior.

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

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

The description is four focused sentences that efficiently cover beta status, current behavior, usage, and a clarification that it is a working router. 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?

Describes the tool's relationship to ask_pipeworx, its current state (no active candidate), and its role as a full-fledged router. Since output is identical to the stable version, lack of an output schema is not a gap.

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

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

Schema covers 100% of parameters with clear descriptions and aliases. The description only says 'same arguments' without adding new parameter-level meaning, 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 identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable sibling by explaining its experimental routing and current state.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router. This gives clear guidance on when to choose this beta 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?

While annotations already declare readOnly, idempotent, and non-destructive hints, the description adds valuable behavioral context: it costs one extra LLM call, it uses only the tool result (no external knowledge), and it returns explicit refusal reasons when data doesn't directly answer. This goes well beyond the annotations and fully discloses 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 front-loaded with the main purpose and is logically structured: purpose, mechanism, return format, usage guidance, and cost comparison. It is longer than average but every sentence provides essential information for a complex tool. Slight verbosity in the middle sentence prevents a perfect score, but it remains efficient.

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

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

The description is complete for a tool of this complexity: it explains the routing mechanism, the success output structure, all refusal reasons, the use cases, and the cost trade-off. Even without an output schema, the description fully specifies the return format. It also acknowledges the sibling tool ask_pipeworx, providing necessary context for selection.

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

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

The input schema has 100% description coverage, with the 'question' parameter fully documented and all aliases listed. The description does not add any parameter-specific meaning beyond saying it 'fills arguments' internally, which is redundant given the schema. Baseline 3 is appropriate because the schema already handles parameter semantics.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' and differentiates it from the sibling tool ask_pipeworx by emphasizing that it extracts answers ONLY from tool results. The verb 'extracts' and the explicit mention of returning evidence and refusals make the purpose specific and unambiguous.

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

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

The description provides explicit 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). It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups,' and explains the trade-off (extra LLM call). This is exemplary alternative differentiation.

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

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

The description extensively discloses behavioral traits beyond annotations: resolver contract with match confidence, safety short-circuits for low-confidence matches, closed-market status, wide-spread tradeability warnings, resolution-rule risk parsing, and news fallback mechanisms. This goes far beyond the readOnlyHint/idempotentHint annotations, giving agents critical context for interpreting results.

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

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

The description is quite long, but it is well-structured with labeled sections (RESOLVER CONTRACT, SAFETY, NEWS FIELDS, etc.) and front-loaded with the primary purpose. Every section contributes operational detail needed for correct use. It is longer than ideal for quick parsing, but the organization prevents it from feeling bloated.

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

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

Given no output schema, the description comprehensively explains return shapes (result.market, result.analysis, result.evidence), resolver fields, parent-event extraction, news fallback fields, and various status codes. It also covers safety mechanisms and resolution-rule risks, making it highly complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage of all three parameters with descriptions and examples. The tool description adds little beyond the schema—it restates the market input forms (slug/URL/question text) and does not explain depth or include_raw in more depth. The classifier list and fan-out examples are more about internal behavior than parameter semantics, so the description does not meaningfully augment the schema.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and details the internal process (resolve, classify, fan out, return packet). This distinguishes it from sibling tools like polymarket_edges, which are for broader edge scanning, making the purpose unambiguous.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. However, it does not explicitly name alternative sibling tools or state when not to use it, so it lacks the exclusions that would earn a 5.

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

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

While annotations already declare readOnlyHint and non-destructive behavior, the description adds valuable context: it retrieves specific financial/clinical data, handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is detailed yet well-organized, with trigger phrases upfront, then behavior, then data specifics. Every sentence contributes useful information without padding or repetition.

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

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

Without an output schema, the description fully explains the return value (paired data + citation URIs), covers both entity types, notes sorting behavior, and even mentions edge-case handling (off-calendar fiscal years). This is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by detailing what each type ('company' vs 'drug') actually fetches (10-K fields, FAERS counts) and how the output is sorted. It also gives concrete examples for values, adding practical 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 is highly specific: it lists common trigger phrases, defines the resource (2-5 companies or drugs), and states the action (side-by-side comparison in one parallel call). It explicitly differentiates from sequential single-pack lookups, which is key among the sibling tools.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides trigger examples and clarifies what data each type retrieves, making it clear when to use this tool versus alternatives.

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

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

Adds extensive behavioral context beyond annotations: account/plan requirements, gap[] reporting with a 'never invented' guarantee, contradictions[] for standard/thorough depths, citation_uri resolvability conditions, semantic excerpting, and expected latency. No contradiction with the readOnlyHint/idempotentHint/openWorldHint annotations.

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

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

Though lengthy, every clause earns its place: prerequisites, exclusions, mechanism, output shape, caveats, depth options, and performance expectations. The content is dense and front-loaded with the most critical constraints (account required, alternatives). 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?

For a complex tool with two params and no output schema, the description covers prerequisites, when to use vs alternatives, internal decomposition and routing, return packet structure, contradictions, citation semantics, excerpts, and latency. It leaves very little ambiguity for an agent to invoke correctly.

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

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

Schema covers both params at 100%, but the description adds significant meaning: depth is defined by hop counts and behaviors (quick=3, standard=5 with gap recovery, thorough=8 with iterative leads and contradictions), and question is clarified as 'natural language. Broad/multi-part is fine — decomposition is the point.' This goes well beyond the schema's field descriptions.

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

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

The description states it performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and sibling ask_pipeworx, making the purpose unambiguous and differentiated.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part structured-data questions; use ask_pipeworx for single lookups and for breaking/colloquial current-news topics; if not signed in, use ask_pipeworx. It also explains depth-tier behavior and fallback options, making alternatives 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it returns top-N relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly with no second schema lookup. This goes 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 opens with a concise, clear purpose ('Find tools by describing the data or task') and then adds a dense but purposeful enumeration of covered domains and a clear value proposition. It is a little long, but every sentence contributes useful information; 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?

The description tells the agent exactly what the tool returns (top-N tools with names, descriptions, full schemas, and curated examples) and how to invoke it first for discovery. With no output schema, this return-format explanation is essential and sufficient. It completely covers selection and invocation context.

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

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

Schema coverage is 100% — all six parameters (query and its aliases, limit) are fully described in the input schema. The description provides context for the query parameter ('describing the data or task') and lists example domains, but adds no syntax or format details 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 clearly states the tool finds tools by describing a data or task, with an explicit verb ('Find tools') and a specific resource ('tools'). It also distinguishes itself from sibling data-retrieval tools by positioning itself as the first step to browse the option set, not just to answer one question.

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

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

It explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use the tool and implies that other tools are for executing specific tasks rather than discovering 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 read-only/idempotent/non-destructive behavior. The description goes further by disclosing the fan-out design ('ONE parallel call'), the fallback chain ('GDELT→GNews fallback'), the soft-fail for patents ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and the deterministic sorting of fundamentals. It also reveals the URI format for filings. This is rich behavioral context beyond what annotations provide, with no contradictions.

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

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

The description is long but information-dense. It opens with the most important user-intent examples, then states the core purpose, then enumerates returns and input constraints. Each clause contributes new facts (sources, fallback, sorting, URI scheme, limitation). It is well-structured and front-loaded, though slightly verbose compared to a minimal version. It earns high marks for organizing a lot of necessary detail.

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 multi-source complexity and the absence of an output schema, the description is remarkably complete. It covers the full input contract (ticker/CIK, exclusion of names), enumerates every return field (cik, company_name, recent_filings with URIs, fundamentals with sorting, patents, news, LEI), describes data sources and failure modes, and even mentions the API sunset. An agent has everything needed to invoke it correctly and interpret results.

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

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

The schema already fully documents both parameters (type enum and value format) at 100% coverage, so the baseline is 3. However, the description adds practical semantics by providing concrete examples ('AAPL', '0000320193'), clarifying the zero-padded CIK requirement, and restating that names are not supported. This helps the agent format valid input values, adding value over 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 starts with concrete natural-language triggers ('Tell me about X', 'company profile for Microsoft') and a precise statement: 'full cross-source profile of a US public company in ONE parallel call.' It names the specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and output fields, and explicitly differentiates itself from sibling single-lookup tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' This makes the tool's purpose unmistakable.

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

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

We have explicit guidance: 'ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' That is a clear when-to-use directive. Additionally, the description states 'names not supported (use resolve_entity first if you only have a name)', giving a specific alternative and exclusion. This is strong guidance on when to choose this tool versus alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds little beyond the action itself; it mentions clearing sensitive data but doesn't describe irreversibility or other side effects. However, no contradiction exists.

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

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

Two sentences: first states the operation, second provides usage guidance. No unnecessary words, front-loaded with the verb.

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

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

For a single-parameter destructive tool with annotations covering safety and idempotency, the description gives sufficient context (when to use) and pairs with complementary tools. No output schema needed. 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 has full coverage (100%) for the single 'key' parameter with description 'Memory key to delete'. The description reinforces 'by key' but adds no new parameter details; baseline 3 applies.

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

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

Description opens with 'Delete a previously stored memory by key' – a specific verb (delete) and resource (memory by key). This clearly distinguishes it from siblings like remember and recall, which store and retrieve memories 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with remember and recall, providing relationship 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' and clarifies that output is a 'single text blob ready to drop at site-root/llms.txt.' This extends beyond the structured annotations.

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

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

The description is well-structured: it opens with the core purpose, then the process, then a short bullet-like 'Useful for' list. It is concise and front-loaded, though the 'Useful for' list adds a bit of length that is slightly redundant with the first sentence but still provides useful context. Overall, every sentence contributes to understanding.

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

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

The description is complete for a simple tool with two parameters and no output schema. It explains the input ('any URL'), the process (fetch page, extract title/description/key links), the output format (standard llms.txt markdown, single text blob), and the intended use cases. An agent has enough information to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for both parameters (url and max_links), so the schema already explains their meaning. The description does not add any parameter-specific details beyond the schema, which is acceptable given the high coverage. It neither clarifies default behavior (e.g., max_links default 25) nor adds examples beyond the schema.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' with a specific output format ('standard llms.txt markdown'). It names the target audience (AI crawlers like ChatGPT, Claude, Perplexity) and distinguishes itself from sibling tools by focusing specifically on generating llms.txt rather than scanning visibility or researching entities.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use the tool, though it does not mention when not to use it or explicitly contrast with alternatives like ai_visibility_check.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by specifying exactly what metadata is fetched (fields, geometry type, record count, capabilities), which goes beyond the annotation signals. No contradictions or unexpected side effects are disclosed, but the description is sufficiently transparent for the tool's simplicity.

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?

One concise sentence front-loads the action and resource, followed by a compact list of return items. Every word earns its place with no redundancy or padding.

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

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

For a one-parameter read-only tool with rich annotations and full schema coverage, the description is complete. It names all major categories of returned information, and no output schema exists, so the description's enumeration of fields, geometry type, record count, and capabilities fully covers the expected result.

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

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

The input schema has 100% coverage for the single 'url' parameter, including a full example. The description mentions 'by url' but adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate as the schema carries the semantic load.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('ArcGIS Feature/Map Service layer's schema') plus the exact information returned (fields, geometry type, total record count, capabilities). This distinguishes it from siblings like query_layer, which presumably retrieves data rather than schema.

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

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

The description implies when to use the tool (when you need schema metadata) but does not explicitly contrast it with query_layer or other data-retrieval siblings. No direct exclusions or alternative tool names are provided, so the guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value beyond annotations by specifying that results are scoped to 'the caller's active subscriptions' and by listing the exact response fields, giving the agent a clear expectation of the return payload and default 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 two sentences and front-loaded with the primary action. The first sentence states the verb and resource, the second adds return fields and usage guidance. Every sentence earns its place; there is no fluff or repetition of schema/annotation 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?

This is a simple list tool with one optional parameter and no output schema. The description compensates for missing output schema by listing return fields. It also provides clear user intent (review before adding, find ID to cancel) and default behavior. For its complexity, the description is complete and self-contained.

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

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

Schema coverage is 100%: the only parameter (include_inactive) has a description in the schema. The description does not mention the parameter but reinforces the default behavior by saying 'active subscriptions.' Per the rubric, with high coverage the baseline is 3; the description does not add significant new meaning 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 begins with a specific verb+resource: 'List the caller's active subscriptions.' It clearly distinguishes from siblings like subscribe/unsubscribe by focusing on listing, and it enumerates the exact return fields (id, type, params, etc.), leaving no ambiguity about the tool's 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?

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly connects to sibling tools (subscribe/unsubscribe) and provides actionable context. It also implies the default scope (active subscriptions) and the purpose of finding IDs for cancellation.

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

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

Since annotations provide no safety signals (all hints false), the description carries the full burden. It discloses the claim_token flow, daily digest reading, rate limit of 5 per identifier per day, free usage without quota impact, and roadmap influence. No contradiction with annotations. This is rich 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?

Though the description is lengthy, every sentence delivers distinct value: purpose, use cases, exclusions, claim_token behavior, rate limits, and cost. It is front-loaded with the primary purpose and flows logically. No filler or redundancy—appropriate detail for a tool with nuanced usage.

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 (claim-token follow-up, exclusions, free tier) and the absence of an output schema, the description is remarkably complete. It explains what happens upon filing, how to follow up, and what to include/exclude. The lack of an output schema is compensated by the description's mention of the claim_token and status return.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics beyond the schema: it tells users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, and clarifies that claim_token should be passed with no other arguments to read a previous report. This enriches the message and claim_token parameters.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools like ask_pipeworx or discover_tools by defining its role as a reporting channel for tool issues, gaps, and praise.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion criterion—do not report tools from other MCP servers—and directs the user to file those elsewhere. This is textbook when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count) tuples, and is cached for 5min-1h depending on window. 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 efficiently organized: a clear opening sentence, a numbered list of use cases, then two final sentences with important caveats. No redundant or excessive wording; every sentence contributes value.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage scenarios, data origin, privacy, return payload shape, and caching behavior. The annotations cover safety, so nothing is missing for an agent to successfully invoke and interpret results.

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

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

Schema coverage is 100% and the schema description already explains the window semantics, including the note about shorter vs longer windows. The tool description merely references the window options without adding new meaning, so it meets the baseline of 3 but does not exceed it.

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

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

The description uses a specific verb ('Returns') and clearly identifies the resource ('top tools, top packs, and total call volume over a recent window'). It distinguishes from siblings like search_datasets or discover_tools by focusing on aggregated trending usage rather than discovery or search.

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, giving clear context for when to call this tool. It does not explicitly mention when not to use it or name alternative tools, so it narrowly misses a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description goes far beyond: it discloses the fill check with live CLOB depth, the warning that realizable_edge_pp ≤ 0 means 'do not trade it,' the Jaccard similarity threshold of 0.30, and the placeholder fraction filter that nullifies arb signals. This is rich behavioral context 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 lengthy but extremely well-structured with uppercase section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose statement. However, it's slightly over-detailed in places, such as explaining Jaccard thresholds and placeholder fractions, which could be summarized more tersely 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?

Given the tool's complexity (3 modes, multiple heuristics, and no output schema), the description is remarkably complete. It enumerates response fields like opportunities[] and partition_check, explains edge cases (skipped_low_similarity, thin_legs), and provides actionable trading advice. No critical information is missing 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 baseline is 3, but the description adds substantial meaning to both parameters. It explains the exact semantics of `event` versus `topic`, gives concrete slug examples like 'fed-decision-may-2026', and details how each mode behaves internally (walks child markets, computes partition_check, etc.). This goes well beyond the schema.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and explains what each does, differentiating this tool from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends 'event (recommended for a specific market)' and cross-event mode as a better catch for certain patterns. It even names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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 a read-only, idempotent operation. The description adds substantial behavioral context beyond that: caching ('Cached 1h at the KV level keyed on all knobs'), diagnostic output ('_diagnostics... so callers can see WHY a segment is empty'), and practical caveats ('your edge may already be in the price', '1m-T vs EFFR signal is unreliable'). This far exceeds the minimum required.

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 wall of text covering model formulas, gate thresholds, response payloads, and knobs without any paragraph breaks, bullet lists, or section headers. While the first sentence front-loads the purpose, the rest is overwhelming and hard to skim. It would benefit greatly from structured formatting even if the content stays the same.

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

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

The description is remarkably complete: it explains the three response segments, the fields carried by each opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.), the top-level response shape (by_segment, fed_candidates/fed_note, _diagnostics), and caching behavior. Since there is no output schema, this prose is essential for the agent to fully understand the return value and debugging information.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds extra meaning by explaining knob interactions: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and the nuance of min_partition_leg_kelly (why min_kelly doesn't filter partition arbs). It also gives real-world context for slippage_pp ('Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp per trade').

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly specifies the verb, resource, and purpose. It further distinguishes from siblings by detailing three distinct model families and tradeable-edge knobs, leaving no ambiguity about what the tool does.

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

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

The description explicitly frames the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also warns about limitations (Fed signal unreliability, rare-by-design longshots) and knob effects, but it does not explicitly name alternatives or provide when-not-to-use guidance. This is clear context but lacks explicit exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive hints. The description goes far beyond that by disclosing cache-miss snapshot writes, the 60-day snapshot TTL, decay computation from daily closes of edge_pp_net (net of slippage), and the signed nature of edge values (negative = SELL YES). This provides significant behavioral context absent from annotations. No contradiction.

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

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

The description is longer than typical but every sentence delivers essential information. It is structured with clear labels (Args, RESPONSE, LIMITS) and an upfront purpose statement. There is no fluff, repetition, or vague language; the word count is justified by the complexity of the tool's behavior.

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

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

Despite lacking an output schema, the description explicitly details the response structure (tracked[], expired[], snapshot_dates[]) with field names and semantics, explains limiting conditions (snapshot TTL, cache-miss gaps, history start point), and describes how trend/decay metrics are computed. This makes the tool's behavior fully predictable without needing extra documentation.

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

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

Schema description coverage is 100%, with both days and window having descriptive text. The description restates these definitions and adds the term 'snapshot family,' but this is essentially a synonym for what the schema already says. Since the schema carries the full load, the description adds no critical semantic value beyond the baseline.

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

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

The description clearly identifies the tool as tracking edge persistence and decay over time from daily polymarket_edges snapshots, answering a specific question: 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (current edges) and polymarket_arbitrage. The verb 'track' and the explicit research question give a precise 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 provides clear context about when the tool is valuable (e.g., a fresh wide edge vs. a 3-week-old wide edge represent different trade opportunities) and explains data availability limitations (snapshot gaps, TTL). However, it does not explicitly name alternatives or state when not to use the tool, though sibling names implicitly draw the contrast.

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, destructiveHint=false, and idempotentHint=true. The description adds substantial behavioral context beyond this: it says the tool 'walks the ladder', lists exact return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), and warns about 'forced_directional_risk.' No contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose. Every sentence adds operational detail, yet the final sentence about 'dominant loss mode in real arb-bot P&L' is somewhat narrative and could be trimmed. The dense paragraph format could benefit from bullet lists for two modes, but it remains focused and 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?

Given the tool's dual-mode complexity and lack of output schema, the description is thorough: it enumerates all return values for both modes, explains parameter semantics, provides usage thresholds, and describes the risk rationale. No important aspect is left unexplained.

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

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

All 4 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds significant extra meaning: it explains the market vs event mode distinction, clarifies that size_usd is interpreted as 'max spend on buys, target proceeds on sells' in single-market mode and as 'settlement notional' (shares per leg) in basket mode, and notes the default and clamp bounds. This goes well beyond the schema.

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

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

The description opens with a specific verb+resource statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. It also explicitly names the two modes (single-market and basket), leaving no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), naming alternatives and giving a concrete threshold.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral context: it details the response structure (leg-by-leg prices, matched spreads), explains compatibility_warning conditions (bet shape mismatches, semantic mismatch), temporal alignment implications (aligned:false means mathematically meaningless), and drop counters (skipped_cross_type/subtype). This is far beyond 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 front-loaded with the core purpose and uses caps-labels (TWO MODES, RESPONSE, SAFETY FIELDS) to organize dense information. It is longer than average, but every sentence carries meaningful detail—edge cases, counter semantics, and temporal alignment. A few phrases are repeated (e.g., 'pre-mapped ≠ tradeable'), slightly padding length, but overall it is structured and efficient.

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

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

With no output schema, the description fully compensates by enumerating response elements: 'leg-by-leg prices... matched spread[].top_spreads_pp', compatibility_warning triggers, temporal_alignment fields, and skipped_cross counters. It also covers edge cases (matched_pairs:0 with or without skipped_cross_type). For a complex tool with 3 optional parameters and no output schema, this is exceptionally 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% and each parameter already has a description (e.g., topic lists values, kalshi_event_ticker and polymarket_event_slug have examples). The description adds value by explaining the interplay: 'Overrides the topic-mapped side,' and clarifying the two modes. This enriches the parameter semantics without being redundant.

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 purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the two venues and the concept of comparing identical outcomes, distinguishing it from sibling tools like polymarket_arbitrage which focus on a single venue. The scope is well-defined.

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

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

The description explains two modes (topic shortcuts vs explicit ticker/slug) and provides strong contextual warnings: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This tells the user when results may be meaningless. It stops short of explicitly naming alternative tools, but the guidance is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral value by specifying that the tool returns attribute rows and geometry, and that the query is SQL-like with configurable parameters. It does not mention authentication or rate limits, but for a read-only public data query tool this is sufficient; 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 the first sentence stating the purpose, the second listing the key parameters, and the third offering a concrete usage example. It is front-loaded, concise, and every sentence contributes value. No filler or redundancy.

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

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

Given the tool's simplicity and the rich annotations/schema, the description covers the necessary context: what it queries, the URL source, the SQL-like parameters, and the return type. It lacks explicit detail on pagination semantics or output format, but these are partially covered by the schema and are not critical for a read-only query tool. Overall, it is sufficiently complete.

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

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

All six parameters are fully described in the input schema (100% coverage), so the description's mere list of parameter names adds little semantic value. The schema already explains each parameter's format and defaults. The description's only additional enhancement is the sampling tip for where/out_fields, which provides a small usage pattern 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 core action: 'Query an ArcGIS Feature Service / Map Service layer by its url (from search_datasets)'. It uses a specific verb ('Query') and identifies the resource type, distinguishing it from sibling tools like search_datasets (which finds datasets) and layer_info (which presumably returns metadata). The mention of returning attribute rows and geometry further clarifies its purpose.

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

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

Provides practical context by noting the URL comes from search_datasets and suggesting a sampling pattern (where="1=1" + out_fields="*"). However, it does not explicitly mention when to use this instead of alternatives like layer_info or search_within, nor does it state any exclusions. This is clear usage context but lacks direct alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds scoping details ('Scoped to your identifier') and the listing behavior when key is omitted, providing extra behavioral context 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 primary action, and each clause adds value (scoping, paired tools). No waste.

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

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

For a simple single-parameter recall tool, the description covers purpose, usage, scoping, and relationships. It omits explicit error behavior on missing keys, but annotations and schema cover safety and parameter semantics.

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

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

The schema already fully describes the 'key' parameter with 100% coverage, and the description adds examples of saved values but no additional parameter syntax or constraints beyond the schema.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys' which clearly states the action and object. It distinguishes from siblings by explicitly naming 'remember' and 'forget' as complementary tools.

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

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

It explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch' and pairs with 'remember to save, forget to delete,' providing clear when-to-use guidance and alternatives.

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

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

Description contradicts annotations. Annotations declare readOnlyHint: true and idempotentHint: true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing, non-idempotent operation. This is a direct contradiction, so the score must be 1.

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

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

The description is three sentences, front-loaded with the core action, then details return fields, filtering, and mark_read semantics. Every sentence adds value with no redundancy or filler.

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

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

For a tool with no output schema, the description explains return fields (source, citation_uri, raw payload), filtering options, mark_read behavior, and even alternative access. It lacks error/edge-case details, but overall it is sufficiently complete for a read-like tool. The annotation contradiction is covered elsewhere.

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 per-parameter descriptions. The description adds extra meaning by explaining mark_read's effect ('so the next call only shows newer ones') and framing type/since as combinable filters with an example. This goes beyond the schema's basic descriptions, justifying a score 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 states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (alerts on the persisted feed) and the return content (source, citation_uri, raw event payload), distinguishing it from siblings like list_subscriptions or recent_changes.

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

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

The description provides useful context: filtering by type and since, marking events read, and notes that polling works fine. It even mentions an alternative access method (the HTTP feed for scripts/dashboards). However, it does not explicitly state when to prefer this tool over siblings or when not to use it, so it falls short of a 5.

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

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

Adds substantial behavior beyond annotations: parallel fan-out to SEC EDGAR, GDELT precedence with GNews fallback on rate-limit/5xx, USPTO sunset soft-fail, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with readOnlyHint or idempotentHint.

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

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

Though dense, every sentence earns its place: examples, source behavior, parameter formats, fallback logic, and an alternative tool. The structure front-loads the purpose with user query examples and then provides necessary operational detail without bloat.

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?

Compensates for the missing output schema by describing return shape (changes[], total_changes, citation URIs) and grouping. Includes entity type limitation, fallback chains, and a clear redirect to entity_profile for static needs, making it complete for a multi-source 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 already covers all 3 parameters, but the description enriches them with concrete formats: 'since' accepts ISO date or relative shorthand ('7d', '3m', '1y') and recommends '30d' or '1m'. 'value' accepts ticker or zero-padded CIK, adding practical guidance.

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

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

The description explicitly states the tool provides a change feed for a company in the last N days/weeks/months, with vivid examples like 'What's new with X' and 'updates on Acme'. It also distinguishes itself from the sibling tool entity_profile, clarifying 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?

Clearly says when to use the alternative: 'Use entity_profile instead when you want the static profile...'. It also describes the internal source fallback (GDELT→GNews) and soft-fail for USPTO, giving concrete context for when results may be partial.

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

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

Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description adds critical behavioral details: key-value pairs scoped by identifier, persistent memory for authenticated users, and a 24-hour retention for anonymous sessions. This enriches the agent's understanding of side effects and lifecycle.

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

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

The description is compact and well-structured, starting with the core action, then usage context, then storage details, and ending with related tools. Every sentence adds value 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 simple save operation with only two parameters and no output schema, the description covers purpose, usage, persistence behavior, and relationships to sibling tools. No critical information is missing.

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

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

Schema coverage is 100% with both 'key' and 'value' having descriptive examples. The description does not add additional parameter-specific semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Save') and identifies the resource ('data the agent will need to reuse later'), with clear distinction from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.' It fully clarifies that this tool stores information across conversations or sessions.

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 tells when to use: 'Use when you discover something worth carrying forward...' and provides alternative tools ('recall' and 'forget') for retrieval and deletion. This gives the agent clear decision criteria.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses several behavioral traits: identifiers are labeled with source, unresolved identifiers are explicitly listed, LEI/FIGI enrichment degrades gracefully, and internal cascading through multiple endpoints. These add substantial context about what happens during execution and failure modes.

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

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

Although lengthy, every sentence carries useful information: example queries, usage rule, type-specific behavior, degradation handling, and internal call structure. The description is front-loaded with examples and a clear directive, and the structure organizes the two supported types logically.

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

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

With no output schema, the description must convey return expectations. It does so thoroughly: for company type, it lists all identifiers and ownership details; for drug, it mentions RxCUI/ingredient/brand and the citation link. It also covers graceful degradation and unresolved fields, making it a complete guide for a tool with this complexity.

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

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

Schema coverage is 100%, so parameters are already well-defined. The description adds meaningful semantics: it explains what each type returns (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand) and gives concrete examples for the value parameter. This enriches the schema without being redundant, though not exhaustive enough for a 5.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides specific verb+resource and differentiates from siblings by listing example queries and supported types (company/drug). It even instructs to use it first when a name needs an ID, showing exactly when it is the right tool.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces multiple manual lookups. While this establishes clear context, it does not explicitly mention when not to use it or name alternatives (e.g., entity_profile), so it narrowly misses 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, covering the safety profile. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, and returns a ranked list with score, confidence, and signal density. It also notes the first entity is treated as the 'subject' for narrative, which is beyond schema.

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

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

The description is two sentences, front-loaded with the core purpose, followed by process, use case, and return output. Every sentence adds value with no repetition or filler.

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

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

With no output schema, the description appropriately explains the return format (ranked list with score, confidence, signal density). It covers the tool's purpose, process, entity constraints (2-8, first as subject), and an example scenario. For a read-only, non-destructive tool with full schema coverage, this is complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'your brand + N competitors' adds context to the entities parameter, but does not meaningfully elaborate on models, _apiKey, or context beyond what the schema already states. The schema does the heavy lifting.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, naming the specific action (probe, rank, surface) and the resource (competitive AI presence). It distinguishes itself from the sibling tool ai_visibility_check by explicitly mentioning it uses that tool per entity, and from generic compare_entities by focusing on AI visibility scores.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and explains the mechanism (probes each entity with ai_visibility_check). It implies that ai_visibility_check is for single entities, though it does not explicitly state when not to use this tool or mention alternatives by name. The context is strong but not exhaustive.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses compound behavior (fans out across services), latency (5-30s first measurement), graceful degradation, and explicit failure reporting (sources_failed). 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 substantial but each sentence carries valuable information: purpose, data sources, use cases, return fields, ecosystem constraints, and failure behavior. It is front-loaded with the core purpose and uses punctuation for readability. A slightly tighter structure would earn 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?

For a composite tool with no output schema, the description is remarkably complete: it lists the exact return fields, explains failure handling, provides latency expectations, and clarifies the ecosystem limitation. An agent has all necessary context to invoke and interpret the result.

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

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

The input schema already provides 100% coverage of both parameters, including defaults and scoped-package acceptance. The description adds ecosystem scope nuance ('NPM ecosystem only in v1') but does not significantly enrich the meaning of the parameters beyond what the schema states.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, naming specific data sources (deps.dev and bundlephobia) and kinds of information returned. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on npm dependency scanning.

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

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

Provides explicit usage triggers ('Use whenever an agent asks...') and even specifies an alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is clear guidance on when to use this tool versus others.

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/destructive hints. The description adds behavioral context: the search scope (Carlsbad GIS open data), the returned fields (name, summary, record_count, owner/org, url), and the downstream usage. This exceeds the baseline without contradiction.

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

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

Two sentences, front-loaded with the purpose, then the output contract. No redundant verbiage.

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 3 simple optional params, no output schema, and good annotations, the description provides the key output fields and downstream flow. It doesn't explain search semantics or sorting, but it's sufficient for effective selection and invocation.

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

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

Schema coverage is 100% with descriptions for query, limit, and org_id. The description adds a keyword-centric framing and notes the default org implicitly through the scope, but does not provide additional parameter-level semantics beyond the schema.

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

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

The description uses a specific verb ('Search') with a specific resource ('City of Carlsbad GIS open geospatial datasets') and lists return fields, distinguishing it from sibling tools like query_layer and layer_info.

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

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

It states the tool searches datasets by keyword and explicitly directs the resulting url to query_layer/layer_info, giving a usage flow. It does not explicitly state when not to use it, but the context is clear for a search-first workflow.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds substantial behavioral detail beyond structured fields. It discloses the technical implementation: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also highlights the value of character offsets for verification, which is useful for an agent deciding when to trust results.

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

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

The description is appropriately sized at about 100 words, front-loaded with the core function, then usage context, then technical details. Every sentence contributes value: it states purpose, gives a when-to-use, names a sibling, and describes the embedding/truncation behavior. There is no filler or redundancy.

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

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

Since there is no output schema, the description explains the return format: 'top-N passages with character offsets and similarity scores' and 'every passage carries an offset so the agent can verify a verbatim quote.' It also covers edge-case behavior with truncation, which is critical for long inputs. The explanation is sufficient for an agent to understand what results look like and how to use them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new parameter semantics beyond what the schema already provides; it repeats the 'max ~200K chars' and includes example queries that are already in the schema. No additional clarification about parameter types, constraints, or interactions is given.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record' and explains exactly what it does: 'Pass the text you already pulled ... plus a natural-language query; get back the top-N passages with character offsets and similarity scores.' It distinguishes itself from siblings by explicitly referencing 'ask_pipeworx_grounded' as a companion tool, and the context of 'too big to cram into the prompt' differentiates it from other query tools.

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

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

The description provides explicit usage context: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also states the alternative path: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly tells the agent when to use it and how it relates to a sibling 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?

Adds behavioral context beyond annotations: requires a Pipeworx OAuth account, cannot persist for anonymous/BYO, phone must be verified for SMS, and a 10/day cap. This enriches the write/idempotent hints provided by annotations.

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

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

The description is densely informative with a logical order (purpose, return, requirements, types, delivery). No wasted sentences, though it omits webhook, which is a completeness issue, not a conciseness one.

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 many important aspects (return id, auth, delivery channels), but it omits two subscription types and the webhook delivery channel—both present in the schema. While the schema compensates, the standalone description is incomplete for an agent relying on it alone.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds specific examples for sec_8k, polymarket_edge, and fred_series params (e.g., items:["5.02"], topic:"fed", series_id:"UNRATE"), offering clarity beyond the schema's more generic text.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. Verb 'create' + resource 'subscription' distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides context about OAuth requirements and mentions feed retrieval via recent_alerts, but the 'Supported types' list is incomplete—missing patent_grant and clinical_trial (present in schema). This could mislead an agent into thinking those types are unsupported, which is a significant gap in usage guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context beyond that: it explains that the tool draws from a live catalog of thousands of tools, returns example questions with tool+argument shapes, and provides category details. This extra context is useful and doesn't contradict any annotation.

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

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

The description is fairly long but front-loaded with example phrases that immediately indicate the tool's purpose. Every sentence provides distinct value: examples, output content, parameter behavior, and strategic usage guidance. Minor verbosity in the middle but no wasted space.

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 an onboarding meta-tool, the description is complete. It explains what the tool returns (category-bucketed example questions with tool+argument shapes), how to call it (no args vs topic), and its relationship to other meta-tools. With no output schema, this description adequately covers expected return values and usage context.

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

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

The schema describes the `topic` parameter fully, but the description adds valuable semantics: it lists example topics (finance, pharma, betting), explains the parameter is optional, and clarifies that omitting it yields a cross-category spread. This goes well beyond the schema's enum-like list and helps the agent decide how to invoke the tool.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions with exact tool and argument shapes. This precise verb+resource+scope distinguishes it from sibling tools like ask_pipeworx or deep_research, positioning it as the 'FIRST' exploratory step.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to focus using the optional `topic` parameter and when to omit it, providing clear context for both use and non-use.

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

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

The description adds significant behavioral context beyond the annotations: ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This precisely explains the non-destructive nature (aligning with destructiveHint=false) and idempotent behavior (implied by deactivation) in a way annotations alone do not convey.

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

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

The description is concise and front-loaded with the primary action, 'Cancel a subscription by id.' Each subsequent sentence adds necessary information about ownership and side effects without redundancy. The entire description is three sentences and earns every word.

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 mutation tool with no output schema, the description covers the essential context: what it does, ownership constraints, and the persistence behavior. It lacks explicit mention of the return format (e.g., success message or updated object), but given the tool's simplicity and annotations, this is a minor gap rather than a critical omission.

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?

Input schema description is 100% complete for the 'id' parameter, but the description adds extra semantic value by specifying 'by id' and clarifying that the id must refer to the caller's own subscription. This reinforces ownership, going beyond the schema's simple 'uuid returned by subscribe'.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription' and parameter 'by id', clearly stating the tool's purpose. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by describing the reverse operation, making the action unambiguous.

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

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

The description provides clear context for use: cancel a subscription by id, but only your own due to ownership enforcement. It indicates when-not-to-use (cannot cancel others' subscriptions) and implies when to use (when you want to deactivate a subscription). It does not explicitly 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?

Beyond the annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true), the description adds substantial behavioral context: the automatic routing between a structured SEC EDGAR fast path and a grounded pipeline, the meaning of each verdict, and a critical warning that 'could_not_verify' means the check did not happen and must not be presented as evidence. This goes well beyond what annotations 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 detailed but every sentence earns its place. It is front-loaded with user-friendly examples, then explains the two-path pipeline, the return structure, and a critical caller warning. The structure is logical and avoids wordiness.

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 correctly explains the return values: verdict list, grounded/structured value with citation, and reasoning. It also clarifies ambiguous verdicts (could_not_verify vs. unsupported) and notes that it replaces 4–6 sequential calls. For a tool of this complexity, the description is fully complete.

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

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

Schema coverage is 100%, so the parameters are already well documented. The description adds extra meaning for `tolerance_pct`, explaining that it overrides the tolerance implied by the claim wording and suggesting values (1–2%) for hallucination detection. This enhances the schema description without redundancy.

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

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

The description clearly identifies the tool's purpose with a specific verb ('validate') and resource ('claim'), anchored by multiple natural-language query examples ('Is it true that…', 'fact check', 'verify the claim that…'). It distinguishes this from general Q&A tools by specifying the verdict-based output and the two distinct verification pipelines (SEC EDGAR structured path vs. grounded fallback).

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 whenever the agent needs to check whether something a user said is factually correct.' It also explains how different claim types are routed internally. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of the top score.

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