Arcgis Loudoun

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral context: the default model is free, passing `_apiKey` incurs direct Anthropic costs, and the response is a per-model object plus a combined view. This goes well beyond the annotations and enriches the agent's understanding.

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

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

The description is compact and well-structured: it front-loads the purpose, then covers model options/cost, return format, and use cases in just three sentences. Every sentence earns its place with no redundancy.

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

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

The tool has no output schema, but the description adequately compensates by detailing the return format. Combined with the full schema explanations and annotations, it covers input, output, model selection, cost, and use cases, making it complete 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?

The schema already describes all 4 parameters with 100% coverage. The description reinforces the relationship between `_apiKey` and `models` and mentions the free default model, but it does not add substantive meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: probing LLMs and producing a 0-100 visibility score per model. It also specifies the return format (score, confidence, signals, raw_response) and names concrete use cases, distinguishing it from sibling tools like scan_competitor_ai_presence by emphasizing scoring rather than mere presence 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?

The description provides explicit usage scenarios (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifies when to pass `_apiKey` to also probe Anthropic. It lacks explicit 'use this instead of X' exclusions, but the context is sufficient for an agent to select the tool appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context beyond annotations: it mentions automatic routing ('Routes the question to the right one of 5,529 tools'), argument filling ('fills arguments'), and output format ('stable pipeworx:// citation URIs'). It does not mention failure modes or rate limits, but the annotations cover the safety profile, making this a solid 4.

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?

Despite being longer than typical, every sentence earns its place. It opens with the key 'PREFER OVER WEB SEARCH' directive, then gives concrete scenarios, examples, alternatives, and disclaimers. The use of caps, line breaks, and examples improves scannability. No fluff is present.

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 exceptionally complete given the tool's complexity. It covers the tool's role, scope (SEC filings, FDA data, etc.), usage triggers, example queries, relationship to alternatives, and return format (citations). Since there is no output schema, the description appropriately steps in to explain the structured answer with citation URIs. This fully addresses what an agent needs to know.

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%: the schema already documents the 'question' parameter and its aliases with a clear description. The tool description itself doesn't add parameter-level semantics, but the examples provided ('What was Apple's revenue in 2024?', 'Any recent SEC filings for $NVDA?') illustrate usage. Since the schema fully covers parameter semantics, a baseline of 3 is appropriate.

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

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

Description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' The verb 'routes' and the emphasis on structured answers with citations distinguish it from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names alternatives with specific cases: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This is exemplary usage 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?

Goes well beyond the annotations by disclosing that it's an experimental edge with candidate routing improvements, that no candidate is currently active, and that results are compared against the stable router. Also clarifies it does NOT fall back to nothing—it's a full working router. This is valuable operational context not present in 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?

Four sentences, each earning its place—defines the tool, states current status, gives usage instruction, and resolves a potential misconception. Not overly verbose, but could be slightly tightened without losing 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?

Given the absence of an output schema, the description explicitly mentions 'same response shape' which covers return expectations. It also addresses the beta's current parity with the stable version and its experimental role. Lacks only minor details like error handling or rate limits, but these are not critical for a router with strong annotations.

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

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

Schema coverage is 100% and each parameter has a description. The description adds no additional semantic detail beyond stating 'same arguments' as ask_pipeworx, so it does not elevate beyond the baseline of what the schema already provides.

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

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

Clearly identifies the tool as a beta version of ask_pipeworx that acts as a universal router to 5,529 tools, with the same arguments and response shape. The sibling differentiation is explicit (experimental edge vs. stable router), and the verb 'use' in context makes the tool's function unmistakable.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that it currently matches the stable version exactly. This also implicitly names the alternative (ask_pipeworx) and gives context for when to prefer this beta.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds significant behavioral detail: it explains the refusal mechanism with specific refusal_reason enums, confirms evidence extraction as verbatim quotes, and discloses the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but well-structured: it opens with the core value proposition, then explains the mechanism, return format, use cases, and cost tradeoff. Every sentence provides distinct information, and the length is justified by the tool's complexity and the absence of an output schema.

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

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

The description covers the return payload (including refusal_reason values), the routing/fetching mechanism, the use context (high-stakes reads), and the cost comparison to ask_pipeworx. Given the complexity and lack of an output schema, this is fully complete for an agent to decide when and how to invoke it.

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: all six parameters are aliases for 'question' and are fully described. The tool description doesn't add parameter semantics beyond the schema, which is acceptable given full schema coverage. Baseline of 3 applies.

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

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

The description clearly states that this is a 'hallucination-resistant answer mode for high-stakes reads,' and explains the mechanism: it routes to tools, fetches data, and extracts answers only from tool results. It also distinguishes itself from ask_pipeworx by emphasizing grounded, evidence-based answers with explicit refusal when data is insufficient.

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

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

Explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also provides an alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost as a tradeoff. This is clear when-to-use and when-not-to 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 declare read-only/idempotent/no-destruction, and the description adds extensive behavioral detail: parallel fan-out, resolver confidence mechanics, short-circuiting on low-confidence matches, handling of closed markets, wide-spread illiquidity notes, cancellation-rule parsing, and 24h-move warnings. It even notes blocking behavior and recurring rules-loss 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 very long, but it is front-loaded with the core purpose and well-organized with uppercase headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). No output schema exists, so the detail is largely necessary to convey the complex return shapes. However, some sections could be trimmed (e.g., exhaustive classifier list) without losing crucial guidance.

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

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

The tool has no output schema, and the description compensates by explaining all major response fields (market, analysis, evidence, resolver contract, parent_event), edge cases (low-confidence, closed markets, wide spread), and risk factors (cancellation rule). It covers the tool's full complexity and gives actionable guidance, making it complete for an agent.

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

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

Schema already covers all three parameters with clear descriptions (market formats, depth enum, include_raw). The description repeats these in prose and adds examples, but no new semantic meaning beyond the schema. Since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource—'Research a Polymarket bet by pulling the relevant Pipeworx data'—and clearly explains the process (resolve, classify, fan out, return evidence). It distinguishes itself from sibling tools by focusing on a single bet's research with data packs, not broad market scanning or arbitrage.

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

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

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes blocking conditions (low-confidence, closed markets) that signal when results shouldn't be used. However, it doesn't explicitly mention when to use 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 annotations (readOnly, idempotent, etc.), the description discloses data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled (revenue, net income, adverse events, trial counts), sorting behavior by primary metric, and output structure (paired data + citation URIs). This far exceeds annotation coverage.

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

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

The description is dense but every sentence carries high-value information: trigger phrases, preference over alternatives, data specifics, sorting, and output format. It is front-loaded and avoids filler while being remarkably informative.

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 specifies return contents (paired data, citation URIs), sorting, and entity count limits. It fully covers what a user needs to know for a comparison tool with only 2 parameters, and also notes handling of off-calendar fiscal years.

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 meaning by explaining what each type ('company' vs 'drug') retrieves and providing concrete examples (AAPL/MSFT, ozempic/mounjaro). It also clarifies the values array constraints via examples.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and lists trigger phrases like 'X vs Y' and 'rank these companies'. It clearly distinguishes from sibling tool entity_profile, which likely handles single-entity lookups.

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

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

It explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', establishing clear when-to-use. It also gives per-type guidance (company vs drug) and implies alternatives for single lookups via entity_profile.

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 richly discloses behavior beyond annotations: account requirements, paid tier for thorough depth, expected latency (15-90s), the shape of the findings packet (verbatim evidence, confidence, source, fetched_at, citation), gaps[] that are never invented, contradictions[], hop fields, resolvable citation_uris, and semantic excerpting. This goes far beyond the readOnly/openWorld/idempotent/non-destructive annotations, 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 every sentence carries value: account prerequisites, core function, use-case fit, mechanics of hop recovery, citation guarantees, and latency. It is front-loaded with the most decision-relevant fact (account required, use ask_pipeworx if not signed in) and avoids filler or repetition of schema details beyond what is useful.

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

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

This is a complex tool with no output schema, but the description fully compensates by specifying return packet composition, gap/contradiction behavior, citation resolution, latency expectations, and account/paid-tier constraints. It also clarifies what the tool is NOT for, making selection and invocation reliable.

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%: both 'question' and 'depth' have detailed descriptions, including depth enum values and their hop behavior. The tool description reinforces this (e.g., thorough needs a paid plan) but adds little new parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool performs grounded multi-source research across 1455 structured data sources in one call, decomposing questions and routing to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its 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?

Usage guidance is explicit: it is best for broad/multi-part structured-data questions, while ask_pipeworx is recommended for single lookups and for breaking/colloquial current-news topics. It also notes that signed-out users should use ask_pipeworx, and describes which depth settings to choose (standard vs thorough) based on follow-up needs.

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 behavioral detail beyond the annotations: it returns top-N tools with names, descriptions, and full schemas, and each result is ready to call directly without a second lookup. Annotations already declare read-only and idempotent, so the safety profile is covered. 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 well-structured with a clear purpose, usage context, return behavior, and usage ordering. The domain list is somewhat lengthy but provides concrete examples that help the user formulate queries. Every sentence adds value, and the structure is front-loaded with the core purpose.

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

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

Given the simple parameter set (6 params, 1 required) and no output schema, the description adequately explains what the tool returns and when to use it. It could mention limit defaults or aliases, but the schema covers these details, making the description sufficiently complete for effective use.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters including aliases and examples. The description adds the context that the query should describe the data or task, but it doesn't add 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 uses a specific verb 'Find' and resource 'tools', and clearly states what the tool does: discovering tools based on data or task descriptions. It distinguishes itself from siblings by explicitly listing domains and positioning itself as the first call for tool discovery.

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

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

The description provides clear when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and prioritizes it with 'Call this FIRST when you have many tools available'. It doesn't name explicit alternatives or exclusions, but the context strongly implies when it should be used.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete behavior: fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; return fields with specifics (recent_filings up to 5 with URIs, latest 10-K fundamentals sorted); USPTO API sunset soft-fail; GDELT→GNews fallback; and CIK/ticker input requirements.

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

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

The description is dense and well-organized, front-loading user-facing examples then flowing into usage guidance, return payload, and limitations. It is longer than average but every sentence carries useful info; the only minor deduction is for the length due to repeated examples that could be trimmed.

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

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

With no output schema, the description must explain returned data, and it does: it lists CIK/company_name, recent_filings with pipeworx URIs, fundamentals source/filter/sort, patents status, news fallback, and LEI. It also covers edge cases (names unsupported, API sunset) making it complete for selecting and invoking the tool correctly.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions (type enum with only 'company', value with ticker/CIK and resolve_entity note). The tool description largely restates this input guidance ('Pass ticker AAPL or zero-padded CIK'), adding no 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 clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete trigger examples like 'Tell me about X' and 'brief me on Tesla.' It differentiates from siblings by positioning itself as the holistic-profile option versus chaining single-pack SEC/XBRL/news lookups.

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

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

Explicit when-to-use guidance is given via example queries and the directive 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view.' It also provides a when-not-to-use and alternative: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already convey destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds minimal extra behavior context ('clear sensitive data') but does not detail side effects like whether a missing key is an error. It does not contradict annotations.

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

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

Three concise sentences: the first states the core action, the second gives usage triggers, and the third links to sibling tools. No wasted words, and the structure front-loads the primary purpose.

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

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

The tool is simple (one required parameter, no output schema) and annotations provide safety context. The description covers purpose, usage conditions, and related tools, making it fully complete for an agent to correctly select and invoke it.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete'. The description adds no further parameter-level detail beyond stating 'by key', which is already implied by 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 action ('Delete') and the target resource ('a previously stored memory'), and specifies the parameter ('by key'). It also distinguishes from sibling tools by framing it as the deletion counterpart to 'remember' and 'recall'.

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

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

Explicit usage contexts are provided: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), giving implicit alternatives for other memory operations.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds meaningful process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' plus notes the output is a 'single text blob.' This goes beyond the annotation hints, although it omits error handling or rate-limit specifics.

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 yet comprehensive, leading with the core function, then the method, output, and use cases. Every sentence contributes value with no redundancy or filler, making it easy to parse quickly.

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

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

For a two-parameter tool with strong annotations, the description is complete. It explains the input (any URL), the process (fetch and extract), the output format (standard llms.txt markdown), and realistic use cases. Given no output schema, the explicit note that the output is a 'single text blob' fully suffices for 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 both `url` and `max_links` having descriptive text. The description mentions extracting 'key links' but does not add meaning beyond the schema's explanation of `max_links`. Since the schema already documents the parameters clearly, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') with a clear scope ('for any URL'). It details the output format and use cases, making the tool's purpose unmistakable. Although it doesn't explicitly reference siblings, the unique deliverable (standard llms.txt markdown) inherently distinguishes it from the other listed tools.

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

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

The description provides explicit use cases ('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'), offering clear context for when to invoke the tool. However, it does not mention when not to use it or explicitly contrast with alternative tools, so it stops short of full 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?

The annotations already establish read-only, idempotent, non-destructive behavior. The description adds value by specifying the type of network operation (fetching from a URL) and what information will be returned (fields, geometry type, record count, capabilities), providing behavioral expectations beyond the annotations. 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 a single, front-loaded sentence that efficiently packs all essential information: action, resource, and output components. There is no fluff or repetition, and it is immediately understandable.

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, read-only tool with no output schema, the description fully covers what the agent needs to know: the input (URL) and the returned information (schema fields, geometry type, record count, capabilities). No critical details are missing for effective tool 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?

The input schema has 100% coverage for the single 'url' parameter, so the baseline is 3. The description adds minimal extra meaning, merely reinforcing that the URL is a layer endpoint, which the schema already states. It does not introduce new details about parameter format or constraints.

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 identifies the resource ('ArcGIS Feature/Map Service layer's schema') along with the exact components (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer or search_within, which likely operate on data rather than schema.

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

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

The description clearly implies the tool is for retrieving layer metadata by URL, giving a clear use case. However, it does not explicitly mention alternatives or when not to use it, though the sibling list suggests tasks like querying features are handled elsewhere. This earns a 4 for clear context without explicit exclusions.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds helpful behavioral context: it specifies the return fields (id, type, params, created_at, last_fired_at, fire_count), notes that it is scoped to 'the caller', and implies that only active subscriptions are returned by default. This goes beyond the annotations and clarifies 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 two concise sentences. The first sentence states the core purpose, and the second sentence lists return fields and provides usage guidance. There is no wasted wording, and the information is front-loaded with the purpose first. Every part adds value.

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

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

This is a simple list tool with one optional parameter and good annotations. The description covers the purpose, usage scenarios, and return fields. Although there is no output schema, the description explicitly lists what is returned. Given the tool's simplicity and rich annotations, the description is complete enough for an agent to select and invoke it correctly.

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

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

The input schema has 100% coverage for its single parameter (include_inactive) with a clear description. The tool description does not add any additional semantics about this parameter, but the schema already provides the necessary meaning. The description does clarify the overall return shape, but since the schema fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' This specifies both the verb (List) and the resource (the caller's active subscriptions), and it distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on the listing action. The mention of returning specific fields further clarifies what the tool does.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool (before adding subscriptions or to find an ID for cancellation). It does not explicitly name alternative tools like 'subscribe' or 'unsubscribe', but the context clearly implies them, so it lacks only the direct 'when not to use' guidance.

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

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

The annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden. It discloses rate limiting (5 per identifier per day), free/no-quota behavior, no-account needed, claim_token mechanism, and daily review cadence.

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

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

The description is a single, well-organized paragraph that front-loads the purpose, then covers exclusions, usage mechanics, and constraints. Every sentence adds distinct operational or contextual 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?

Even though there is no output schema, the description explains the return flow (claim_token), how to follow up, rate limits, and scope of what is fixable. It is complete for a feedback tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how claim_token is reused, that message should not paste the end-user prompt, and that filing without an account returns a token.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource statement. It clearly distinguishes this from siblings by limiting scope to 'tools served by this Pipeworx connection' and even contrasts with other MCP servers' tools.

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

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

Provides explicit when-to-use cases: bug, feature/data_gap, and praise. It also states when not to use—when the tool came from a different MCP server—and offers a 'Not sure?' disambiguation rule based on tool names.

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

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

Beyond annotations (read-only, open, idempotent, non-destructive), the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h depending on window. This gives a clear picture of freshness and data provenance.

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 a scannable 'Useful for' list, then adds worthwhile behavioral details. It is somewhat longer than strictly necessary, but no sentence is wasted.

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

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

For a read-only stats tool with one optional parameter, the description covers the return values (top tools, packs, call volume), the window choices, the underlying data source, caching behavior, and privacy characteristics. With no output schema, this is sufficient to set expectations.

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

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

The single 'window' parameter is fully documented in the schema with an enum and explanatory text ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats this idea without adding new parameter-level meaning, so it stays at the baseline for full schema coverage.

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

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

The description opens with a clear, specific question ('What other AI agents are calling on Pipeworx right now') and states the exact outputs: top tools, top packs, and total call volume over a selectable window. This distinguishes it from sibling tools like ask_pipeworx or discover_tools by focusing on aggregated usage trends.

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' section lists three concrete scenarios (spotting current-event data sources, confirming canonical tools before asking a question, checking alignment with agent needs), which is strong when-to-use guidance. However, it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description goes far beyond them by disclosing internal filtering (Jaccard ≥0.30, placeholder fraction >20% returns null) and the fill-check caveat (realizable_edge_pp ≤ 0 means don't trade). It includes explicit 'do not trade it' guidance and response structure, which is more than annotations provide.

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

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

The description is long, but it is front-loaded with purpose and organized into clear mode blocks. It contains a few redundant phrases ('cross-event mode catches...', 'placeholders_filtered') and could be tightened, but overall every paragraph serves a distinct informational role.

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 covers expected return fields (opportunities[], partition_check{}, fill_check with live CLOB depth) and known edge cases (negative realizable_edge, placeholder filtering, low similarity). It also localizes the tool among siblings by referencing polymarket_fill_risk for custom sizing, so an agent can decide whether to call this tool or a complementary one.

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

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

Although schema descriptions already cover both parameters (100% coverage), the main description adds substantial semantic value: event mode explains slug/URL acceptance and walking child markets; topic mode explains seed-question semantics and cross-event flattening. Examples are concrete, and the interaction between the two params is clarified.

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

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

The description opens with a specific verb-resource pair ('Find arbitrage opportunities on Polymarket') and explicitly names the detection mechanisms ('monotonicity violations + partition-sum checks'). It also immediately distinguishes three invocation modes (trending_scan, event, topic), preventing confusion with generic market-analysis 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 provides explicit mode selection: 'Call with NO args for a trending_scan', '`event` (recommended for a specific market)', and '`topic` (for cross-event scanning)'. It also explicitly points to an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and explains the added value of cross-event mode.

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 readOnly, idempotent, non-destructive. The description adds extensive behavioral context: caching for 1h keyed on knobs, the placeholder-slug filter, the 'rare-by-design' longshot gates, the Fed signal caveat, and that partition arbs return kelly_fraction_half=0. 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 highly detailed and structured in sections (model families, response layout, knobs, diagnostics) but is very long. It contains a lot of internal formulas (e.g., '90d FRED log-returns', 'per-sport α') that may be more than an agent needs to invoke the tool correctly. Effective front-loading, but some sentences are dense and could be trimmed.

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

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

With no output schema, the description does a strong job of explaining the response structure: top-level keys, per-segment contents, diagnostics for empty segments, and per-opportunity fields. It also covers parameter effects and caching, making the tool's behavior comprehensible for a complex read-only tool. Missing only exact JSON nesting details, but sufficient.

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

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

All 9 parameters already have detailed schema descriptions (100% coverage). The description adds interaction semantics beyond the schema: which knobs affect tradeable-edge gates, that min_kelly doesn't apply to partitions, and how slippage_pp relates to execution costs. That goes beyond the baseline.

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

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

The description opens with a clear verb-plus-resource statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and details the specific model families, which distinguishes it from sibling tools, though it doesn't explicitly compare against them.

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

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

The description explicitly frames the tool for daily bet discovery and explains how to use tradeable-edge knobs (min_liquidity, max_spread_pp) and warns about parameter pitfalls, e.g., 'min_kelly never filters partition arbs by design'. However, it doesn't explicitly state when to prefer sibling tools like polymarket_arbitrage.

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 readOnlyHint/idempotentHint annotations, the description adds substantial behavioral context: snapshots are written on cache-miss so gaps mean 'nobody scanned that day', history depth is bounded by a 60-day TTL, and decay numbers are computed on daily closes not intraday. It also details the response structure (tracked/expired/snapshot_dates) and the signed edge value convention, which is essential given no output 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?

Though long, the description is organized into sections (Args, RESPONSE, LIMITS) with each sentence adding unique information: purpose, usage context, response format, and caveats. 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 tool with no output schema and moderate complexity, the description covers the response format, trend labels, decay computation, sign convention, data gaps, and TTL limitations. It is self-contained enough for an agent to understand what it will receive and what edge cases exist.

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

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

Both parameters are fully described in the schema (100% coverage), so baseline is 3. The description reiterates days lookback and window snapshot family but does not add new semantics beyond the schema; the 'clamp 2-30' vs 'max 30' nuance is trivial.

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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and explicitly answers 'how long has this edge existed and is it shrinking?' This is a specific verb+resource+outcome that distinguishes it from sibling tools like polymarket_edges.

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

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

The description provides a clear use-case scenario: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It explains the tool is for historical persistence analysis but does not explicitly name alternatives or exclusions, so no 'when-not-to-use' guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it 'walks the ladder', returns fills and slippage, and warns that partial basket fills convert an arb into an unhedged position. It also clarifies the required market-or-event constraint.

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 its core purpose and structured clearly into single-market and basket modes. Every section provides necessary detail for a complex tool, though the last sentence about 'dominant loss mode' is slightly verbose and could be trimmed.

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

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

No output schema exists, yet the description enumerates all key return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk for basket. It also ties usage to sibling tools, making it actionable.

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 each parameter: size_usd is interpreted as 'max spend on buys, target proceeds on sells' in single-market mode and as 'settlement notional' in basket mode; side defaults are auto-selected based on partition sum; clamps are specified (10–1,000,000). This adds mode-specific meaning absent from 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 and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order-book execution rather than opportunity detection.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale, noting that theoretical overround on thin books is not capturable and partial basket fills create unhedged directional positions.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description thoroughly discloses behavior: response contents, compatibility_warning trigger conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It even warns when spreads are mathematically meaningless, which is valuable behavioral context not inferable from annotations.

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

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

The description is dense but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core definition. It is longer than average, but most sentences earn their place given the tool's complexity; a slight reduction in clause stacking would improve readability.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases. It covers leg-by-leg prices, spread computation, compatibility warnings, temporal alignment, and skipped comparisons—making the tool's behavior understandable and actionable without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter interplay: topic is a pre-mapped shortcut, kalshi_event_ticker and polymarket_event_slug override the mapped side, and explicit examples ('KXFED-26OCT', 'fed-decision-in-june-825') are provided. This exceeds the schema's simple property descriptions.

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

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

The description opens with a specific definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (Kalshi–Polymarket spread) and distinguishes it from sibling tools like polymarket_arbitrage and compare_entities by focusing on cross-venue spread and compatibility checking.

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

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

The description gives clear context for when to use the tool: comparing same-question prices across two venues, with explicit modes for topic shortcuts or custom pairings. It also provides when-not guidance ('pre-mapped ≠ tradeable', compatibility_warning cases), but it does not name alternative sibling tools for specific scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns attribute rows and geometry, supports SQL-like filtering and pagination via limit/offset, and suggests a sampling pattern. These are extra behavioral details beyond annotations, 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?

Two sentences, front-loaded with the core purpose, quickly lists the main parameters, states the return type, and ends with a useful tip. Every sentence earns its place with no redundancy.

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

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

For a 6-parameter tool with no output schema, the description sufficiently explains what it returns (attribute rows and geometry), how to filter/paginate, and how to sample. The schema covers parameter details, and annotations cover the safety profile. It doesn't discuss error handling or spatial query alternatives, but it's largely complete for correct invocation.

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

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

Schema description coverage is 100% with detailed explanations for all 6 parameters. The description only lists parameters in prose (where, out_fields, order_by, limit, offset) and adds a small note about using where/out_fields for sampling. This adds marginal value over the schema, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Query an ArcGIS Feature Service / Map Service layer by its url.' It also ties the url to 'search_datasets' and lists the key query parameters, distinguishing this data-retrieval tool from siblings like layer_info (metadata) and search_within (spatial 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 description indicates the workflow by saying 'from search_datasets', implying the dataset must first be found. It also provides a practical sampling tip with where='1=1' and out_fields='*'. However, it does not explicitly exclude alternatives or state when not to use this tool, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds beyond this by disclosing scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual-mode behavior (retrieve by key or list all keys). This is useful context not present in the annotations, though it does not detail return formats or error cases.

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

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

The description is three sentences, each serving a distinct purpose: first defines the core action, second gives the use case and examples, third explains scoping and partnerships with remember/forget. Information is front-loaded and there is no redundant phrasing. It is concise yet informative.

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 (single optional parameter, read-only, no output schema), the description covers its main functionality, usage context, scoping, and related tools. It does not specify the return value shape or behavior when a key is missing, but the absence of an output schema and the clear examples make the description sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and the parameter description already states 'omit to list all keys'. The tool description reiterates the same logic ('omit the key argument') without adding deeper meaning. It offers examples of stored values, but these do not clarify the parameter's syntax or edge cases. Thus it meets the baseline 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 starts with a specific action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly identifies the resource (saved memories), the operations (get by key or list), and provides concrete examples (ticker, address, research notes). This distinguishes it from siblings like remember and forget by focusing on retrieval only.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explains the conditional behavior of omitting the key to list all keys. While it mentions pairing with remember and forget, it does not explicitly state when not to use the tool, so it falls short of a 5.

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

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

The description states that mark_read:true flags events as read, which is a state mutation. However, the annotation readOnlyHint:true declares the tool as read-only, directly contradicting the described behavior. Per the rubric, this contradiction forces a score of 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 main action, and every sentence contributes operational meaning without fluff. It efficiently conveys purpose, return payload, filtering, state behavior, and alternative access.

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

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

Given there is no output schema, the description covers the return payload structure, filtering options, mark_read side effects, polling suitability, and an alternative HTTP endpoint. This is comprehensive for the tool's complexity and the schema already covers parameter details.

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

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

With 100% schema coverage, the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO timestamp format for since, and explaining the effect of mark_read on subsequent calls. This enrichment justifies a 4.

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

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

The description clearly states the tool's purpose with a specific action ('Pull fired events') and resource ('subscription feed'). It also describes the return payload and is distinct from sibling tools like list_subscriptions, which handle subscription management rather than event retrieval.

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 practical guidance on filtering by type and since, using mark_read, and notes that polling works fine. It also gives an explicit alternative via the HTTP endpoint for scripts/dashboards, but doesn't name sibling tools as alternatives, so it's clear 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?

The description goes well beyond the readOnly/idempotent annotations by detailing the multi-source fan-out, fallback logic, date parsing (ISO or relative shorthand), and the grouped return structure with total_changes count and pipeworx:// citation URIs. It also notes the PatentsView API sunset, setting expectations for a soft-failure mode.

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?

Despite being longer than average, every sentence is information-dense. It is front-loaded with real user queries, then systematically covers sources, parameters, fallbacks, and return shape. There is no redundancy.

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

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

Given the tool's complexity (three external sources, fallbacks, multiple date formats, no output schema), the description is remarkably complete. It covers the return shape (changes[] grouped by source, total_changes, citation URIs), the alternative tool, and the window semantics, enabling an agent to invoke it correctly without additional 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?

While the schema already covers all three parameters, the description adds meaning: it gives concrete examples of relative vs. ISO dates, recommends '30d' or '1m' for typical monitoring, and clarifies that value can be a ticker or zero-padded CIK. These enrich the schema definitions with 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 opens with concrete user intents ('What's new with X' / 'latest on Y'), then states the tool is a change feed for a company in a recent time window that fans out to SEC EDGAR, GDELT/GNews, and USPTO. It clearly distinguishes itself from the sibling entity_profile tool, which is positioned as the alternative for static profiles.

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 tells when to use this tool vs. entity_profile ('Use entity_profile instead when you want the static profile...'), explains the time-window semantics, and even provides fallback behavior (GDELT preferred, GNews when rate-limited or 5xx; USPTO soft-fails after API sunset). 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?

The description adds critical behavioral details not available from annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and it's a key-value store. These are important operational constraints that the readOnly/idempotent/destructive hints 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 purpose, then usage guidance, then lifecycle details. Every sentence adds value, and there is no redundant or filler content.

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

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

For a simple 2-parameter tool with full schema coverage and clear annotations, the description is complete. It covers purpose, usage, persistence semantics, and sibling relationships, leaving no ambiguity about how to use or invoke the tool.

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

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

Schema description coverage is 100% and both parameters are well-defined with examples (e.g., key as 'subject_property', value as any text). The description only reiterates 'key-value pair' without adding new parameter 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 states the tool saves data for later reuse across conversations or sessions, using a specific verb ('Save') and resource ('data'). It also distinguishes itself from sibling tools recall and forget by explicitly naming them as partners.

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

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

It explicitly says to use when discovering something worth carrying forward, gives concrete examples (ticker, address, preference, research subject), and states the alternatives: 'Pair with recall to retrieve later, forget to delete.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Adds rich behavioral context beyond annotations: graceful degradation of LEI/FIGI enrichment, cascading through multiple endpoints, explicit 'unresolved' reporting, and source-labeling of identifiers. Annotations already declare read-only and idempotent, but the description goes far beyond with operational details.

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

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

The description is long but dense with useful information. It is front-loaded with practical query examples and structured by entity type. Every sentence contributes, though a bit more trimming could make it even more 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?

With no output schema, the description thoroughly covers return values: CIK, ticker, company_name, LEI, FIGI, RxCUI, ingredient, brand, and unresolved fields. It also mentions sources and fallback behavior, making the tool's behavior fully predictable.

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

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

Schema descriptions are strong (100% coverage), but the tool description adds significant meaning: concrete input examples (AAPL, 0000320193, 'ozempic'), explanation of what each type returns, and behavior around unresolved identifiers. This exceeds the baseline 3 for full schema coverage.

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

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

The description states a clear, specific purpose: resolve user-spoken names to canonical/official identifiers. It gives multiple example queries and lists supported entity types with detailed outputs, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID', and notes it replaces 2-3 manual lookups. It doesn't explicitly state when not to use or name alternatives, but the context is clear and actionable.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds behavioral specifics: it uses 'ai_visibility_check' for each probe, ranks by score, identifies most/least recognized, and returns a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

Two concise sentences front-load the core purpose and immediately mention the key differentiator (multi-entity side-by-side comparison). Every clause adds value, from the probe mechanism to the return 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?

With no output schema, the description sufficiently communicates the return structure (ranked list with score, confidence, signal density). It also explains the internal workflow (probe with ai_visibility_check) and the intended narrative (subject vs competitors), rounding out the tool's behavior.

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, so the schema already explains all parameters. The description adds no new parameter details beyond referencing 'your brand + N competitors', which aligns with the schema's 'first entry treated as subject' comment.

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 ('Compare') and resource ('AI visibility across multiple entities'), immediately distinguishing this tool from the single-entity sibling 'ai_visibility_check'. It clearly states the action (probes, ranks, surfaces) and the input/output (entities, rank list).

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 concrete use-case guidance ('competitive AI-marketing audits') with an example question. Implies the alternative of using 'ai_visibility_check' for single entities by stating it probes each entity with that tool, but does not explicitly exclude or compare with other sibling tools.

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

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

Discloses operational details beyond annotations: partial failures degrade gracefully, sources_failed lists timed-out sources, and bundlephobia's first measurement can take 5-30s. Complements the readOnly/idempotent annotations with latency and failure-mode 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 longer than average, every sentence earns its place: one-sentence composite pitch, use-case triggers, return-format list, ecosystem limitation, and failure behavior. Front-loaded with purpose and structured 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 fully enumerates the return fields (summary block, per-advisory detail, links, alternative versions) and covers edge cases like timeouts and ecosystem limits. Complete for a tool of this complexity.

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

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

Schema already covers 100% of parameters with descriptions (package, version). The description adds no substantive parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clear verb+resource: 'scan_dependency' checks if an npm package should be added, with explicit composite behavior across deps.dev and bundlephobia. It names specific checks (license, advisories, bundle size, tree-shaking) and distinguishes itself from sibling tools by stating its exact 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?

Provides explicit usage triggers: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also states when not to use it (NPM only; other ecosystems fall under deps.dev:version directly), giving clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond these: it specifies what the tool returns (name, summary, record_count, owner/org, Feature Service `url`) and that the URL is intended for chaining to query_layer/layer_info. 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 two sentences: the first states the action, scope, and examples; the second lists return fields and the chaining instruction. Every clause carries essential information, no fluff or repetition.

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

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

Although there is no output schema, the description explicitly lists all return fields and how to use the returned URL. Combined with thorough annotations and a fully described input schema, the agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with all three parameters described. The description reinforces the 'query' keyword semantics through examples and adds output chaining context, but it does not add parameter-level details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Search') with a clearly defined resource ('Loudoun County GIS open geospatial datasets') and gives concrete examples (parcels, addresses, zoning & public works). It also differentiates from sibling tools by explicitly stating the returned Feature Service `url` should be passed to query_layer/layer_info, positioning this as the discovery 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 provides clear context: search by keyword to find datasets, then use the returned URL with query_layer/layer_info. This implicitly tells the agent when to use this tool versus those alternatives. However, it does not explicitly state when not to use it or mention alternatives like search_within, so exclusions are only implied.

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 crucial behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and that outputs include character offsets and similarity scores. This adds substantial context not inferable from annotations alone.

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?

Four sentences, each packed with unique information. No redundancy with schema or annotations. The structure is logical: what it does, when to use, how it pairs, and technical specifics. Nothing is wasted.

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

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

Despite no output schema, the description explicitly states return values (top-N passages, character offsets, similarity scores) and covers edge cases (truncation, overlapping windows). It provides enough context for an agent to understand inputs, outputs, and usage scenarios without additional documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the 'text' parameter as previously fetched content, giving query examples, and explaining how the parameters relate to the search mechanics (windows, offsets, top-N). It also explains truncation behavior which affects how 'text' is handled, going slightly beyond schema descriptions.

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

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

The description uses a specific verb+resource ('Semantic search INSIDE a fetched record') and clearly distinguishes from siblings by emphasizing it operates on already-fetched text rather than fetching or answering broadly. It lists concrete examples (SEC 10-K, article) and explicitly differentiates from ask_pipeworx_grounded by explaining the complementary workflow.

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

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

Provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and directly names the alternative/when-not-to-use pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context for 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?

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description goes far beyond these: it notes the OAuth requirement, non-persistence for anonymous/BYO, delivery channel options (feed, email, SMS, webhook), SMS verification and 10/day cap, webhook signing secret one-time exposure, and auto-disable after 10 consecutive failures. This is detailed behavioral disclosure and does not contradict 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 front-loaded with the core purpose in the first sentence, then organized by auth, types, and delivery. While lengthy, each sentence adds needed information for a complex tool; no filler is present.

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?

No output schema is provided, but the description states the primary return (subscription id) and the one-time webhook secret. It also covers auth, all supported types, param formats, delivery channels, limits, and how to retrieve alerts. This is highly complete for a create-operation tool.

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

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

Schema coverage is 100% with detailed per-parameter descriptions. The description adds concrete examples for each subscription type (e.g., sec_8k items:['5.02'], polymarket_edge topic:'fed', fred_series series_id:'UNRATE') and clarifies constraint semantics like phone verification and caps. This enhances the schema without redundancy.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This states a specific verb (create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions and unsubscribe. It also enumerates supported subscription types, making the tool's scope unmistakable.

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

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

The description explains that subscriptions are for proactive monitoring and requires an OAuth account, which helps users decide when to use it. It also mentions how to consume alerts via recent_alerts or the registry URL. However, it doesn't explicitly compare with alternative tools like list_subscriptions or unsubscribe, though those are implied by sibling names. Clear context but no explicit when-not-to-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?

Annotations already declare this as a safe, read-only, idempotent operation. The description adds meaningful behavioral context about the output: it returns category-bucketed example questions with 'the exact tool + argument shape' drawn from the live catalog, and explains the no-argument vs. topic-focused behavior. This goes beyond the structured annotations without contradicting them.

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

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

The description is longer than strictly necessary, but it is front-loaded with example queries and then structured into purpose, output, parameter behavior, and usage guidance. Every section earns its place, though the sentence containing the full category list is somewhat dense; still, it remains efficiently organized.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it explains what the tool returns, the categories covered, how the parameter modifies behavior, and when to use it. The absence of an output schema is compensated by the description clearly stating the output structure (category-bucketed example questions with tool+argument shapes).

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

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

The schema description already covers 100% of the single `topic` parameter, listing all valid values and the omit behavior. The tool description adds only marginal redundancy by naming a few example topics ('finance', 'pharma', 'betting'), so it does not significantly enhance parameter understanding beyond what the schema provides.

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

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

The description clearly identifies this as the onboarding entry point for an agent that just connected, with a specific verb ('Returns category-bucketed example questions') and resource (Pipeworx's tool catalog). It distinguishes itself from siblings by explaining it teaches how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities, which no other sibling does.

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

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

The description explicitly states when to use it: '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 provides clear context and direction, though it does not explicitly name alternative tools or when not to use it, which would raise it to a 5.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement, deactivation rather than deletion, and that historical events remain accessible via recent_alerts. This complements the annotations (e.g., destructiveHint=false) and provides clarity on the tool's side effects.

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

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

The description is concise—three short sentences, each adding crucial information: the core action, the ownership restriction, and the deactivation behavior. No redundant or vague phrasing.

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

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

For a simple one-parameter tool with strong annotations, the description fully covers all key aspects: what it does, who can use it, and what happens to the data. It also connects to 'recent_alerts', showing awareness of the broader tool ecosystem.

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 fully documents the single parameter 'id' with a description. Since schema coverage is 100%, the description does not need to add parameter details, and it doesn't. This is the baseline score for high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation and ownership enforcement.

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

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

The description provides clear context on when to use this tool: when you want to cancel a subscription, with the caveat that you can only cancel your own. It also hints at the alternative of keeping historical events via recent_alerts, effectively explaining the trade-off of cancellation. However, it does not explicitly mention when NOT to use it or compare to other 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 description goes far beyond the annotations by explaining critical behavioral semantics: the difference between 'could_not_verify' (check did not happen, no evidentiary value) and 'unsupported' (no source found), the structured fast path for company financials, and the automatic fallback to a grounded pipeline. It also clarifies that 'could_not_verify' must not be presented as evidence, which is crucial for agent decision-making. This robust transparency greatly exceeds the safety hints already present in annotations.

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

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

The description is fairly long but well-structured: trigger phrases, usage, processing paths, output details, error semantics, and efficiency note. Every sentence adds value, and the use of bullet-like lists (verdicts, error fields) improves readability. It could be slightly more compact, but the density is justified by the complexity of the tool.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so comprehensively: verdicts, actual value with citation, reasoning, and error structures. It also covers the dual-path behavior and parameter nuances. Given the tool's complexity and the absence of an output schema, the description 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?

The input schema already describes both parameters, and the description adds extra meaning by giving a concrete example for 'claim' and elaborating on 'tolerance_pct' with usage guidance (e.g., 'set 1–2 for hallucination detection') and its default behavior. This elevates it above the baseline 3 for full schema coverage, though the additional info is moderate rather than exhaustive.

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 natural-language claim verification with specific trigger phrases ('fact check', 'verify the claim that…', 'confirm or refute'). It distinguishes itself from siblings by focusing on factual verification against authoritative sources and describing the output verdict types. The verb 'validate' plus resource 'claim' is 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear when-to-use guidance. It also outlines two processing paths (company-financial vs any other claim) and notes it replaces multiple sequential calls, implying an efficiency advantage over alternatives. However, it does not explicitly name alternative tools or provide when-not-to-use scenarios, so it stops short of a perfect score.

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