Arcgis Princewilliam

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

Annotations already declare readOnly/idempotent, and the description adds valuable non-obvious context: the default model (Llama-3.3-70b), BYO key cost implications, return shape, and combined view. This goes well beyond the annotations and 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?

Three tightly written sentences: action, default, return shape, and use cases. Every sentence earns its place with no filler. 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?

Despite no output schema, the description explicitly defines the return format. It covers purpose, usage, default behavior, cost, and applicability. Given the tool's moderate complexity and rich parameter descriptions, this is fully self-contained.

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

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

Schema covers 100% of parameters, setting a baseline of 3. The description adds the specific default model identifier and clarifies the billing nuance for _apiKey, which slightly enriches understanding of models and _apiKey beyond the schema text.

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

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

The description clearly identifies the action ('Probe one or more LLMs'), the resource (knowledge about a business/brand/product/topic), and the output (visibility score 0-100). It distinguishes this from sibling tools by focusing on per-model visibility scoring rather than general Q&A or research.

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

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

It provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs extended usage (adding Anthropic via _apiKey). It does not name specific alternatives or state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds value by explaining that the tool routes to many tools, fills arguments, returns structured answers with citations, works on every tier, and is the default entry point. It does not contradict annotations and gives meaningful context about behavior beyond safety flags.

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

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

The description is long but well-structured: it starts with a strong preference directive, lists applicable domains, provides examples, and clearly delineates when to use alternatives. Every sentence adds value, though some redundancy exists (e.g., 'START HERE...' repeats the default entry point idea), so it's not maximally concise.

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

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

With no output schema, the description still conveys the return format ('structured answer with stable pipeworx:// citation URIs'). It covers a broad set of use cases, explains the tool's role relative to siblings, and gives guidance for step-up scenarios. It doesn't mention error handling or rate limits, but for a general question-answering tool, the coverage is strong.

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

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

The schema already covers all 6 parameters (all aliases for 'question') with a clear description of the natural language request. The description does not add parameter-specific details beyond what is in the schema, but it does provide rich example queries in the description text. Since schema coverage is 100%, baseline of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to 5,529 tools across 1,455 sources with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, and it gives concrete examples of use cases.

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

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

The description explicitly instructs to prefer this tool over web search for a wide range of topics, provides trigger phrases ('what is', 'look up', 'find'), and explains when to step up to alternatives ('Step up only when needed: ... use ask_pipeworx_grounded; ... deep_research'). It also addresses the breaking-news case by saying ask_pipeworx already routes to live news.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful context: it is a full working router with no fallback, may change behavior when a candidate is tested, and currently matches ask_pipeworx exactly. This goes beyond the structured hints.

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

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

Three sentences with each earning its place: what it is, current status, and how to use it. No fluff or repetition; it is front-loaded and appropriately sized.

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 (beta variant of a router), the description fully covers identity, relationship to ask_pipeworx, experimental nature, current state, and usage. Even without an output schema, it notes 'same response shape,' making it complete for decision-making.

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 has 100% coverage, clearly defining the 'question' parameter and its aliases. The description only says 'same arguments' without detailing them, so it adds no significant 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 explicitly states it is a beta version of ask_pipeworx with an identical universal router (same 5,529 tools, same arguments, same response shape), and distinguishes it from the stable sibling by noting candidate routing improvements. It clearly conveys the tool's function and 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?

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes the current status (no active candidate) and that results are compared against the stable router, effectively telling when to choose this over ask_pipeworx.

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

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

Beyond the read-only/idempotent annotations, the description discloses refusal behavior with explicit reasons ('not_in_source', 'no_tool_match', etc.), evidence quoting, and the extra LLM call overhead. This fully informs the agent of operational boundaries and failure modes.

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

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

The description is dense with information but remains well-structured: purpose, routing, return format, refusal reasons, usage guidance, and cost tradeoff. It is longer than ideal but every sentence contributes substantial value, earning a 4 rather than a 5.

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

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

Given the tool's complexity (routing across 5,529 tools, extraction, refusal handling) and no output schema, the description fully explains return values, failure modes, and cost implications. It is complete enough for an agent to invoke correctly and interpret results.

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

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

Schema coverage is 100% and the description does not add new meaning to parameters beyond what the schema already states. The description mentions 'question' indirectly but no additional format, constraints, or examples are provided, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and clearly distinguishes from sibling 'ask_pipeworx' by explaining the extra extraction step. It also enumerates the return shape, making the tool's purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of one extra LLM call.

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/openWorld), the description discloses extensive behavioral details: low-confidence resolutions short-circuit with status:"low_confidence_match" and suppress analysis fields, closed markets return "market_closed_or_inactive" and skip fan-out, wide-spread markets carry tradeability:"illiquid_wide_spread", and cancellation rules parse resolution text into refund_50_50 / resolves_no_on_cancel etc. It also explains that both blocking routes are different mechanisms and warns about EV-material losses. This is rich, actionable transparency.

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 uppercase category headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose in the first sentence. It is long (several hundred words) but the density is justified by the tool's complexity. Some fan-out examples could be trimmed, but the organization makes it scannable, earning a 4.

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

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

With no output schema, the description fully compensates by detailing result shapes, resolver contract (confidence levels, alternatives, suggestions), parent_event extractor, news fallback fields, and status codes (low_confidence_match, market_closed_or_inactive). Safety mechanisms and resolution-rule risk are also covered, leaving no major gap for the agent to size bets safely.

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

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

The input schema already provides detailed descriptions for all three parameters (market, depth, include_raw) with 100% coverage. The tool description does not add new parameter-level semantics beyond what the schema states; its fan-out examples are illustrative but do not alter the meaning of the parameters. Thus the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further details the mechanism: resolves the market, classifies the bet, fans out to data packs, and returns an evidence packet with market-vs-model comparison. This clearly distinguishes it from sibling tools like ask_pipeworx or validate_claim by focusing on the full research 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?

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of a 5.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. No contradictions with annotations.

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

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

The description is dense and front-loaded, but includes slight redundancy ('ALWAYS PREFER' and 'Replaces 8–15 sequential lookups' convey similar points). However, every sentence contributes to usability, and the length is justified by the tool's complexity.

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

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

The description covers triggers, type-specific behavior, data sources, sorting logic, return format, and comparisons to alternatives. Even without an output schema, it gives a clear picture of what to expect, making it complete for a tool with this complexity.

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

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

Despite 100% schema coverage, the description enriches parameter meaning by explaining how 'type' determines data source and metric, and gives concrete examples for 'values' (e.g., AAPL/MSFT, ozempic/mounjaro). It also clarifies constraints like 2-5 items and what is compared.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with explicit trigger phrases. It distinguishes itself from sequential lookups and sibling tools like entity_profile, 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?

It provides explicit when-to-use guidance via trigger examples and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates behavior for type='company' vs type='drug', giving clear context for selection.

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, openWorld, idempotent), the description adds valuable behavioral context: account/plan requirements, latency expectations (15-60s, up to 90s for thorough), gap handling (gaps[] never invented), contradictions[] for standard/thorough, citation_uri only when fetchable, and semantic excerpting of large records. No contradiction with annotations.

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

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

The description is long (multi-paragraph) but information-dense; every sentence contributes to usage, behavior, or output. It is front-loaded with the most critical operational constraint (account requirement) and structured logically. Slightly verbose for a tool description but justified by the complexity.

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

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

Given no output schema, the description thoroughly explains the findings packet, gap recovery, contradictions, citation URIs, and hop fields. It also covers prerequisites, latency, and fallback alternatives. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds extra semantics for depth: 'standard re-angles unanswered gaps' and 'thorough additionally chases the best leads.' Also clarifies question is meant for broad/multi-part queries, adding value over the schema's generic description.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It also distinguishes from siblings by explicitly noting 'this is NOT open-web search' and referencing ask_pipeworx as an alternative for different use cases.

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

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

Clearly states when to use: 'Best for broad/multi-part questions over structured data.' Provides explicit alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also gives a pre-auth fallback: 'If you are not signed in, use ask_pipeworx instead.'

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail: returns top-N tools with full input schemas and examples, and that results are ready to call directly without a second schema lookup. This goes beyond the annotations and aids the agent in interpreting the response.

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 informative and front-loaded with the core purpose. The list of domains is somewhat long but directly helps the agent decide when to use the tool. Every sentence contributes value, though it could be tightened slightly.

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 relatively simple tool with one required parameter, the description thoroughly covers purpose, usage, return format, and even mentions no second lookup is needed. It compensates for the lack of an output schema by describing what is returned. It doesn't cover pagination or edge cases, but these are not significant for this tool.

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

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

Schema description coverage is 100%, so each parameter is already well-documented. The description adds minor context like 'top-N' and 'curated examples,' but does not substantially enhance parameter semantics beyond the schema's existing descriptions.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly differentiates itself from sibling tools by being a meta-tool for discovery, listing many domains it covers. This makes the purpose unmistakable.

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

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

Provides explicit context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when not to use (when you already have a specific tool), but does not name alternative sibling tools or provide explicit exclusions, so it falls slightly short of a 5.

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

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

Adds rich behavioral context beyond the safe-read annotations: 'ONE parallel call', 'Fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF', 'PatentsView API sunset May 2025 — soft-fails until reactivated', 'GDELT→GNews fallback', 'up to 5' filings, and 'sorted period_end DESC'. These details disclose failure modes and execution characteristics not visible 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?

Despite its length, every sentence carries information: front-loaded with example queries and purpose, then structured enumeration of return fields and limitations. The density is justified by the tool's complexity and the absence of an output schema to lean on.

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 specifies return contents (cik, recent_filings with URIs, fundamentals, patents, news, LEI), input constraints, and failure behavior. It covers all necessary context for an open-world, read-only tool, leaving no major gaps.

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

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

Schema description coverage is 100%, and the tool description essentially repeats the schema's parameter explanations (ticker/CIK examples, names not supported, use resolve_entity). No new semantic meaning is added beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('full cross-source profile') and resource ('US public company'), and distinguishes from siblings by explicitly preferring over 'chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity. Example queries like 'research Acme' and 'company profile for Microsoft' further anchor purpose.

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

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

Provides explicit when-to-use guidance: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack...'. Also gives when-not-to-use: names not supported, instructing to 'use resolve_entity first' if only a name is available, and notes the patents soft-fail.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description's 'delete' confirms destructiveness but adds little beyond the annotations—just a motivation about sensitive data. It does not detail irreversibility, permissions, or behavior on missing keys, but with annotations covering the core traits, a 3 is appropriate.

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

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

Two sentences, front-loaded with the action and object, then use cases. Every word earns its place; no redundancy or filler.

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

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

For a simple one-parameter tool with no output schema and idempotent/destructive annotations, the description provides enough context: what it does, when to use it, and its relationship to sibling tools. It could mention return values or error cases, but those are not critical given the tool's simplicity.

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

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

The input schema provides full coverage of the sole parameter 'key' with description 'Memory key to delete.' The description's phrase 'by key' adds no new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' It clearly states the operation and the object, and distinguishes it from sibling tools like remember and recall by targeting deletion rather than storage or 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 gives explicit use cases ('context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember and recall. However, it does not explicitly state when not to use it or name an alternative tool for non-deletion cases, so it stops short of a 5.

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

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

The description discloses the internal behavior (fetch, extract, emit) and the output format ('single text blob ready to drop at site-root/llms.txt'), adding context beyond the readOnly/idempotent annotations. It does not contradict the annotations and explains the network read operation implied by openWorldHint.

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 well-structured sentences plus a use-case list. It is front-loaded with the primary action, followed by process/output and usage examples. 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?

With no output schema, the description explicitly states the return value and format ('single text blob ready to drop at site-root/llms.txt'). It covers the core behavior and use cases, though it omits error scenarios or rate limits. For a simple URL-to-text tool with supportive annotations, this is 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?

Schema coverage is 100% with clear descriptions for both 'url' and 'max_links'. The description adds minor context ('for any URL', 'key links') but does not substantially enhance understanding beyond 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?

The description states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It also details the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'), which clearly distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The 'Useful for' list provides explicit contexts: getting a client's site indexed, drafting llms.txt for your own project, or auditing a competitor. It gives clear when-to-use guidance, though it does not mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the bar. The description adds value by specifying what the tool returns (fields, geometry type, count, capabilities), giving expectations without contradicting the annotations.

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

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

The description is a single, front-loaded sentence that packs all necessary information without fluff. Every phrase earns its place, listing the tool's purpose and key outputs.

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

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

For a simple read-only schema retriever with one required parameter and rich annotations, the description is complete. It explains the return contents (fields, geometry type, count, capabilities), and no output schema is needed because the description fully covers what to expect.

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

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

The input schema provides 100% coverage for the single 'url' parameter with a clear description and example. The tool description adds no extra parameter semantics beyond naming 'url', so the schema carries the burden.

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 resource ('ArcGIS Feature/Map Service layer's schema') and lists the exact contents returned (fields, geometry type, record count, capabilities). This clearly differentiates it from siblings like query_layer, which would focus 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 implies when to use the tool: when you need schema details for a layer identified by URL. However, it does not explicitly mention alternatives, exclusions, or compare with sibling tools, so usage guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotent, and non-destructive. The description adds valuable context by specifying the caller scope, the default active-only behavior, and the exact fields returned. It stops short of discussing pagination or error behavior, but for a simple read-only tool this is strong transparency.

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-load the purpose and then provide return details and use-case guidance. Every sentence is informative; no fluff or redundancy. This is exemplary conciseness.

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

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

For a simple list tool with no output schema, the description adequately covers purpose, return fields, and use cases. It misses minor details like whether results are paginated or sorted, but the tool is simple and the provided context is sufficient 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?

The input schema has 100% coverage with a clear description for 'include_inactive'. The description does not add parameter-specific details, but it does reinforce the default behavior by saying 'active subscriptions'. This meets the baseline of 3 for a well-documented 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 the specific verb 'List' and resource 'the caller's active subscriptions', clearly distinguishing it from sibling subscribe/unsubscribe tools. It also enumerates the return fields, reinforcing the tool's 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?

The description explicitly states when to use the tool: 'before adding more' subscriptions and 'to find an id to cancel'. This provides practical guidance tied to sibling operations, showing the tool's role in the subscription workflow.

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

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

Annotations are all false, so the description carries the burden. It discloses key behaviors: filing returns a claim_token if no account, the token can be used later to read status/changes, the team reads digests daily, and it's free and doesn't count against quota. It doesn't explicitly state whether the feedback record persists or how it is stored, but the disclosed behavior is sufficient for an agent to understand side effects and follow-up semantics.

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

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

The description is a single dense paragraph of about 130 words, but every sentence earns its place (purpose, when-to-use, exclusions, claim_token flow, rate limit, quota note). It could be broken into bullet points for readability, but it is not bloated or redundant. The information density is high and appropriately front-loaded.

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

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

With no output schema, the description fully explains what the tool returns (a claim_token when no account, and status/changes when claim_token is passed). It also covers rate limits, quota impact, and the acceptable scope of feedback. For a 4-parameter tool with nested objects and no output schema, the description is remarkably complete and leaves no major unanswered questions 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 coverage is 100%, so parameters are already well documented. The description adds extra value by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), giving guidance on what to describe in message ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), and clarifying the context structure. This goes beyond just restating the schema.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It precisely defines the tool's scope and inherently distinguishes it from siblings like ask_pipeworx (which presumably answers questions) by focusing on feedback submission.

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 explains when to use the tool ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...'), and provides a strong exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' Also mentions practical limits (rate-limited to 5 per identifier per day), giving complete guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the data provenance ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('5min-1h depending on window'), which enriches the safety and freshness profile.

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

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

The description is compact and structured with a lead sentence, bullet-like use cases, and a concise data/caching note. No fluff; all sentences add value.

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

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

Despite lacking an output schema, the description covers the core return items, data format, privacy, and caching. It's sufficient for a simple one-parameter read-only tool.

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

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

Schema coverage is 100% and the schema description already explains window semantics. The tool description merely repeats the '24h, 7d, or 30d' options without adding new parameter meaning, so it matches the baseline 3.

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

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

The description clearly identifies the tool as a read-only analytics endpoint returning top tools, packs, and call volume over time windows. It distinguishes itself from sibling tools by focusing on agent demand signals ('What other AI agents are calling on') and mentions specific outputs.

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 'Useful for' use cases covering current events discovery, canonical tool confirmation, and demand alignment. However, it does not name alternative tools or state when not to use it, so it's clear on context but lacks 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 description goes far beyond the annotations. It discloses thresholds (3pp, 0.30 Jaccard, >20% placeholder), explains the partition_sum check, the fill verification with CLOB depth, and warns 'do not trade it' when realizable_edge ≤ 0. It also explains the semantic anchor and skipped_low_similarity. No contradiction with readOnlyHint=true.

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

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

The description is lengthy but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence conveys needed operational detail for a complex two-mode tool. Slightly verbose but not wasteful; earns its length.

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

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

Given the tool's complexity (two modes, fill check, multiple thresholds) and no output schema, the description covers all essential aspects: return fields, edge cases, safety checks, and cross-mode behavior. It is complete enough for an agent to invoke correctly and interpret results.

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

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

Although schema coverage is 100%, the description adds significant semantic value: event expects slugs or full URLs, topic expects seed questions, and it explains how each mode behaves beyond the schema descriptions. It also describes response details per mode, adding meaning not present in the input schema alone.

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?

Starts with a clear verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique arbitrage-detection mechanism and mentioning fill_risk for custom sizing.

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

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

Provides explicit mode selection: no args for trending_scan, event for a specific market, topic for cross-event scanning. It recommends event for specific markets, gives concrete examples, and even points to polymarket_fill_risk for custom sizing. This is exactly the kind of when-to-use alternative guidance desired.

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, but the description goes far beyond this by revealing response structure, model families, caching behavior, diagnostics, and edge-case handling (e.g., placeholder filters, Fed exclusions). This significantly enhances agent understanding of what the tool does and its operational quirks.

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 remarkably comprehensive but far from concise. It contains extensive technical detail (per-sport α, exact gate thresholds, pipeline internals) that might be valuable but could overwhelm an agent. It is well-structured with clear sections, but it borders on over-specification for the purpose of tool selection and invocation.

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

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

There is no output schema, so the description fully carries the burden of explaining the return format. It details top-level structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields, and diagnostics that help callers understand empty segments. Combined with the schema's parameter coverage, no critical context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context about knobs (e.g., 'TRADEABLE-EDGE KNOBS' and min_partition_leg_kelly behavior) but this is largely redundant with the schema's detailed parameter descriptions. No additional semantics are provided beyond the schema.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker, and the detailed model-family breakdown further clarifies the tool's unique value.

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 phrase 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets' provides clear usage context and an explicit use case. However, it does not name alternatives or state when not to use this tool versus siblings, which would be necessary for a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behavioral traits: 60-day TTL bound, snapshot gaps due to cache-miss, decay computed on absolute edge value with signed direction, and daily-close basis rather than intraday. This gives the agent critical expectations about data availability and computation.

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

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

The description is long but well-structured with sections for intent, args, response, and limits. Every sentence adds value, though the response component details could be considered dense. It is appropriately organized and 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?

Despite no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]) and their semantics, along with limitations. This makes the tool fully understandable for an agent without additional docs.

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 provides complete descriptions for both parameters (days and window) with defaults and allowed values. The description repeats this information, adding no new semantic meaning beyond what the schema covers. Baseline 3 applies due to 100% 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?

Clearly identifies the tool as edge persistence/decay telemetry built from daily polymarket_edges snapshots. It explicitly states the core question it answers ('how long has this edge existed and is it shrinking?') and distinguishes it from the raw polymarket_edges tool by focusing on historical time-series and 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?

Provides clear context on when to use: when you need historical persistence and decay of edges, contrasting fresh vs old wide edges. However, it does not name alternative tools or state explicit when-not-to-use conditions, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by detailing input requirements (one of market or event), default values (size_usd default 1000, side default), output fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and the risk of partial basket fills converting an arb into an unhedged directional position. It also explains size_usd interpretation per mode. No contradiction with annotations.

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

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

The description is long but well-structured with all-caps section markers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and a clear one-sentence opening definition. It is front-loaded and scannable. Some redundancy exists (e.g., the thin-book risk warning repeats the earlier 'theoretical overround on thin books' concept), but the length is largely justified by the tool's complexity.

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

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

With no output schema, the description thoroughly lists return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk for basket). It also covers edge cases (partial fills, thin books), provides a size threshold ($500), and explains the verdict categories. This is complete for a complex tool.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds mode-specific context not fully present in the schema, such as how size_usd is interpreted differently in single-market ('max spend on buys, target proceeds on sells') versus basket ('settlement notional S') modes, and clarifies valid parameter combinations. While much of the parameter info is repeated from the schema, the mode integration adds meaningful selection 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 a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then clearly delineates two modes (SINGLE-MARKET and BASKET) and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate its role as a pre-trade validation tool. This is a specific, well-scoped purpose.

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

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

The description explicitly instructs when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional positions) and provides mode-selection requirements ('REQUIRES one of market or event'). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral detail: the compatibility_warning conditions with two specific cases, temporal_alignment semantics (aligned:false means spreads are meaningless), and how skipped_cross_type/subtype counters explain dropped comparisons. This far exceeds the structured annotation baseline.

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

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

The description is long but highly structured, with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Every sentence carries substantive information, though a few details (e.g., the exhaustive skipped_cross_type explanation) could be trimmed without losing value.

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

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

With no output schema and a complex tool (3 optional params, multiple edge cases), the description fully compensates: it explains the response shape (leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, skipped counters), and covers all relevant caveats including the warning that pre-mapped topics are not automatically tradeable. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds crucial parameter semantics: it enumerates the 10 topic shortcuts with examples, explains that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and clarifies the custom pairing mode. This adds meaning beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly scopes the tool's function and outlines two distinct modes (topic shortcuts and explicit tickers), making the purpose unmistakable and differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description gives explicit usage context: it defines the two modes, explains when the delta is a 'real signal' (equivalent bet shapes) versus when it isn't, and warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics currently return compatibility_warning. It does not name alternative tools for exclusion, but the usage boundaries are clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it returns 'attribute rows (and geometry)', uses SQL-like where clauses, and supports pagination via limit/offset. It also hints at sampling behavior. 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 two sentences with the primary action front-loaded. The first sentence states the tool's core function and inputs; the second sentence provides a practical usage tip. No filler or redundant text—every word earns its place.

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

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

For a 6-parameter tool with no output schema, the description covers the essential aspects: what it queries, how to obtain the URL (via search_datasets), what it returns (attribute rows and geometry), and a simple usage example. It omits details like pagination response structure or error behavior, but the schema and annotations fill most gaps. The reference to sibling usage adds context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats parameter semantics already in the schema (e.g., 'SQL-like where', 'comma-separated out_fields'), adding no new per-parameter meaning. The sampling tip (where='1=1' + out_fields='*') is a useful combination but does not elevate semantic understanding beyond schema.

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

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

The description clearly states the action: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It specifies the resource type and distinguishes the tool from siblings like search_datasets (discovery) and layer_info (metadata) by focusing on returning 'attribute rows (and geometry)'. The parameter list reinforces purpose.

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

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

The description explicitly mentions that the URL comes 'from search_datasets', establishing a prerequisite workflow. The sampling tip ('Use where="1=1" + out_fields="*" to sample') provides a concrete use case. However, it does not explicitly state when to use this tool versus alternatives like layer_info or search_within, 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?

Annotations already declare the tool as read-only and non-destructive, but the description goes beyond this by revealing scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the ability to list all keys. These are meaningful contextual details that annotations do not capture, providing the agent with essential behavioral 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 concise (three sentences) and front-loaded with the primary function. Each sentence earns its place: the first states the core operation, the second provides usage context and examples, and the third explains scoping and complementing tools. No wasted words or redundant restatement of schema fields.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description is remarkably complete. It covers behavior (retrieve/list), usage rationale (avoid re-deriving), scoping, and integration with siblings. The only potential omission is error behavior for missing keys, but this is mitigated by the absence of an output schema and the tool's read-only nature.

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

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

Schema coverage is 100% (the 'key' parameter is fully described in the schema). The description adds value by elaborating on what kinds of keys might be stored ('the user's target ticker, an address, prior research notes'), giving the agent concrete expectations for parameter values beyond the schema's brief definition.

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 ('Retrieve') and resource ('a value previously saved via remember'), clearly distinguishing the tool from siblings like remember (save) and forget (delete). It also explicitly states the alternate behavior of listing all keys when the key is omitted, leaving no ambiguity about its primary function.

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

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

The description provides explicit when-to-use guidance: '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 references sibling tools for complementary operations ('Pair with remember to save, forget to delete'), indicating the intended workflow and implicitly excluding itself from saving/deleting.

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

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

Annotations already mark readOnly and idempotent, but the description adds the critical mark_read side-effect—'flag returned events read so the next call only shows newer ones'—and discloses the persisted feed nature and payload structure. No contradiction with annotations; the optional mutation is clearly disclosed.

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

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

Three sentences, front-loaded with purpose, then parameter details, then usage context. Every sentence earns its place—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?

The description covers return fields, filter parameters, mark_read behavior, and the alternative REST endpoint. With no output schema, it supplies enough for an agent to invoke and interpret results. Minor gaps like unread_only semantics are already covered by the schema.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds an example type value ('sec_8k'), clarifies 'since' as an ISO timestamp, and explains mark_read semantics beyond the schema. It doesn't cover every parameter, but the schema already handles limit and unread_only effectively.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed,' explicitly listing return fields (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions or recent_changes by focusing on alert events.

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

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

It provides clear usage context: 'Polls work fine' and offers an alternative HTTP endpoint for scripts/dashboards. It also explains when to use mark_read to advance the feed. However, it doesn't explicitly compare to sibling tools or state when not to use it, so it's clear but not fully contrasted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes far beyond annotations, disclosing non-obvious behaviors: it 'fans out' in parallel, uses a GDELT→GNews fallback on rate-limit/5xx, and notes the USPTO/PatentsView sunset 'soft-fails until reactivated.' It also states the output shape (grouped changes[], total_changes count, pipeworx:// URIs), providing complete transparency into what the agent will receive. 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 dense but every clause earns its place. It leads with the most useful part (user-question examples), then the core behavior, then sources and fallbacks, then parameter formats, then return structure, then the alternative tool. No fluff or repetition of schema fields. For a tool with this much behavioral nuance, the length is justified.

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

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

Given 3 required params, complex multi-source fan-out, fallback logic, and no output schema, the description is remarkably complete. It covers input formats, source behaviors, failure modes, output structure, and usage boundaries (via the entity_profile redirect). The agent has all contextual information needed to decide when and how to invoke this tool correctly.

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

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

The input schema already has 100% parameter descriptions, but the description adds substantial semantic value. It provides formats and examples for `since` ('ISO date ("2026-04-01") or relative shorthand ("7d", "30d", "3m", "1y")') and clarifies `value` can be a ticker or zero-padded CIK. The `type` parameter's constraint ('Only company supported today') is reiterated. This enriches the schema's baseline with practical syntax 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 example queries ('What's new with X', 'latest on Y') and states its core function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It then enumerates specific data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), giving a precise scope. It also explicitly distinguishes itself from the sibling tool entity_profile, making its unique purpose unmistakable.

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

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

This is exemplary. It gives clear conversational triggers (e.g., 'news on Tesla recently') and then says 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This explicitly tells the agent when NOT to use this tool and names the alternative. It also documents the fallback chain for news sources (GDELT preferred, GNews when rate-limited or 5xx), which is essential operational 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?

While annotations already indicate idempotent (true) and non-destructive (false), the description adds significant behavioral context: key-value storage scoped by identifier, persistence for authenticated users, and a 24-hour retention for anonymous sessions. These details go beyond the annotations and help the agent understand side effects and lifetime.

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

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

The description is four sentences, each adding necessary information: purpose, usage examples, storage mechanics, and complementary tools. It is front-loaded with the primary action and contains 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 two-parameter write tool, the description covers purpose, usage, persistence, scoping, and relationships to sibling tools. Annotations and schema provide the remaining necessary details, making the description complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with both 'key' and 'value' parameters well-defined with examples. The description adds only general context ('key-value pair') but no additional parameter-specific semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Save') and resource ('data the agent will need to reuse later'), and distinguishes it from siblings by explicitly mentioning 'recall' and 'forget' as complementary tools. Examples of use cases (resolved ticker, target address, user preference) make the purpose concrete.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and names alternatives ('Pair with recall to retrieve later, forget to delete'), creating a clear usage context that differentiates it from sibling tools.

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

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

Annotations already declare readOnly/openWorld/idempotent safe behavior, and the description adds substantial behavioral context: it reveals internal cascading ('each call cascades through several lookup endpoints internally'), graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), and explicit unresolved handling ('stated explicitly under `unresolved` rather than omitted'). There is no contradiction with annotations.

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

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

The description is dense but well-structured, opening with natural language query examples then the core purpose. Some redundancy exists with the schema (e.g., accepted input formats are repeated), but each section provides practical value. The length is justified for a tool handling two distinct types with many identifiers.

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

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

Despite lacking an output schema, the description explains returned identifiers, source labeling, the `unresolved` field, and the fact that it replaces multiple manual lookups. It covers both supported types, input variations, degradation behavior, and internal cascading. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

The input schema already covers both parameters thoroughly (100% coverage), so the baseline is 3. The description adds meaning by detailing what each type returns (e.g., company: CIK, LEI, FIGI with source labels; drug: RxCUI, ingredient, brand) and clarifies accepted formats for `value` beyond the schema examples, such as ticker, CIK, or name for company.

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 its function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes itself from sibling tools by positioning it as the first step ('Use FIRST whenever you have a name but need an ID') and lists supported entity types.

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 usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool 'replaces 2-3 manual lookups,' implying a bundling action. However, it does not explicitly state when not to use it or name alternative tools (e.g., entity_profile for existing IDs), so it stops short of full when/when-not guidance.

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

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

Annotations already mark readOnly and idempotent, so description needn't repeat safety. Adds behavioral details: probes each entity, ranks by score, returns ranked list with confidence and signal density, and notes model/API key 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?

Three sentences: purpose, method, use case, and return format. Every sentence contributes, no redundancy, front-loaded.

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

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

Despite no output schema, description explicitly lists return fields (ranked list, score, confidence, signal density). Combined with detailed schema and annotations, provides complete mental model for selection and invocation.

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

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

Schema covers all 4 params with descriptions, but description adds semantic nuance: first entity is the 'subject' for narrative, workers-ai is free default, anthropic requires _apiKey. These enrich beyond 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?

Description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource. It distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking.

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

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

Provides clear use case: competitive AI-marketing audits with example query. It names ai_visibility_check as the underlying probe and implicitly contrasts with single-entity check, but doesn't explicitly exclude other comparison tools like compare_entities.

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

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

Annotations already mark it read-only and idempotent; the description adds behavioral details like partial failure degradation, 5-30s latency on first bundlephobia measurement, and the sources_failed field, without contradicting annotations. This goes beyond safety flags to explain real-world 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 dense but every sentence contributes—purpose, usage triggers, output fields, ecosystem limits, failure behavior. No filler, well-structured, and front-loaded with the main 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 no output schema, the description enumerates return fields (summary block) and covers failure modes, latency, and ecosystem alternatives. It fully equips an agent to invoke and interpret the results, making it exceptionally complete.

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

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

Schema coverage is 100% with descriptions for both package and version parameters. The description adds no additional parameter-specific detail 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?

The description clearly states this is a composite npm package evaluation tool across deps.dev and bundlephobia, with a concrete use case ('should I add this npm package'). It distinguishes itself from siblings by its unique scope and integrated output.

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

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

Explicitly says 'Use whenever an agent asks...' and notes the NPM-only scope, directing non-NPM ecosystems to deps.dev:version directly. 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?

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds concrete behavioral details: it returns metadata fields including name, summary, record_count, owner/org, and the Feature Service url. This goes beyond annotations, though it doesn't disclose rate limits or auth requirements, which are likely unnecessary for a simple search.

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 with no filler. The first sentence states the purpose and scope, the second lists return fields and handoff instructions. Front-loaded and efficient.

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

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

For a search tool with no output schema, the description fully covers what will be returned and how to proceed with the results. Annotations cover safety and open-world behavior. It is complete for its intended use case.

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

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

The input schema already provides 100% coverage with descriptive parameter details for query, limit, and org_id. The description does not add substantial parameter semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool searches Prince William County GIS open geospatial datasets by keyword, with specific examples of datasets. It also distinguishes itself from siblings by explicitly directing users to pass the returned URL to query_layer/layer_info.

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

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

Provides explicit usage context: search by keyword, and then hand off the returned Feature Service URL to query_layer/layer_info. This tells the agent when to use this tool and what to do next, effectively differentiating it from related 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?

Beyond readOnly/openWorld/idempotent annotations, the description discloses the mechanism (BGE-base-en embeddings + cosine over 500-char overlapping windows), output specifics (top-N passages with character offsets and similarity scores), and the 200K char limit with truncation+flagging. This adds substantial operational detail beyond the annotations.

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

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

The description is front-loaded with a clear one-sentence summary, followed by usage context and technical details. Every sentence earns its place: use case, output format, pairing with sibling, and algorithmic constraints. No filler or redundancy.

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

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

Despite no output schema, the description explains what is returned ('top-N passages with character offsets and similarity scores') and the truncation flag. It covers input limits, intended use, and pairing, making it complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by grounding the 'text' parameter as 'the text you already pulled (e.g. a SEC 10-K body)' and gives query examples, which helps the agent formulate inputs. The 200K char cap is already in the schema, but the flagging behavior is new. This is helpful but not transformative.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing the 'already pulled' text and contrasting with ask_pipeworx_grounded, which grounds over the whole document instead of relevant passages.

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 when the record is too big to cram into the prompt.' It also gives an alternative and a pairing with ask_pipeworx_grounded, making the usage scenario unambiguous. Though it doesn't list when not to use, the conditional guidance is strong.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: requires OAuth, feed is always on, phone must be verified, webhook auto-disabled after 10 failures, and webhook signing secret returned only once. 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?

The description is lengthy but well-structured: it front-loads the purpose, then covers requirements, subscription types, and delivery channels in a logical order. While it duplicates some schema content, the density of information justifies the length and the organization aids 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?

For a tool with no output schema, the description states the return value and covers auth, all subscription types with examples, delivery options, verification steps, and failure limits. It lacks explicit error-handling information, but given the complexity of the tool, it is reasonably complete.

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

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

The schema already provides 100% coverage with detailed descriptions and examples for 'type', 'params', and 'delivery'. The tool description repeats much of this information, offering limited new meaning beyond the schema. The only novel additions are the OAuth requirement and the always-on feed concept, which are more about usage than parameter semantics.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' which clearly identifies the action and resource. It also specifies the return value ('Returns the new subscription id') and distinguishes itself from sibling tools like list_subscriptions and recent_alerts by focusing on subscription creation.

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

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

The description provides strong contextual guidance by listing prerequisites (OAuth account), supported subscription types, and delivery channels. It implicitly differentiates from recent_alerts by noting the always-on feed can be pulled via that tool, but it does not explicitly state when not to use this tool or directly compare with unsubscribe.

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 behavior beyond that: outputs are drawn from the live catalog, results are organized by category, each example carries the tool+argument shape, and calling with no arguments returns the full spread while passing topic focuses. This meaningfully supplements the annotations without contradiction.

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

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

Although longer than minimal, the description is front-loaded with purpose and every section earns its place: trigger phrases for what users might ask, the return value summary, the optional parameter behavior, and explicit first-use guidance. It is dense but not bloated.

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

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

There is no output schema, so the description carries the burden of explaining return values. It clearly states that results are category-bucketed example questions with exact tool and argument shape. It also covers the optional topic behavior, the categories available, and usage context, making the tool fully usable from the description alone.

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

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

The schema already covers the single optional `topic` parameter at 100%, so the baseline is 3. The description adds extra meaning by giving concrete examples ('finance', 'pharma', 'betting') and explaining the no-argument vs. topic-focused call pattern, which helps the agent decide how to populate the parameter.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent and says it returns category-bucketed example questions with the exact tool and argument shape needed to answer them. This distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on 'what to ask' rather than just listing tools or answering a specific query.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains that it can also teach how to call meta-tools like ask_pipeworx, entity_profile, and compare_entities. It doesn't explicitly state when NOT to use it, but the wording implies this is the starting point before using those more targeted tools, which counts as clear context.

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

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

The description discloses a critical behavioral trait not conveyed by the annotations: cancellation deactivates the row rather than deleting it, preserving historical events via recent_alerts. It also adds an ownership restriction, which is auth-related context. These details go well beyond the structured annotations, enriching the agent's understanding of 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 two sentences, tightly packed with essential information. The first sentence states the action and target; the second adds ownership and behavioral nuance. Every clause earns its place, with no filler or repetition of structured data.

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

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

For a single-parameter mutation tool with no output schema, the description covers everything an agent needs: what it does, the ownership constraint, the non-destructive deactivation behavior, and the implication for historical data availability. Combined with the idempotentHint and destructiveHint annotations, the context is complete.

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

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

Schema description coverage is 100%, with the single parameter 'id' already documented as 'Subscription id (uuid) returned by subscribe.' The description's phrase 'Cancel a subscription by id' restates this without adding further semantic detail. Per the rubric, the baseline is 3 when the schema carries the full burden, which it does here.

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

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

The description opens with 'Cancel a subscription by id', a specific verb+resource construction that clearly identifies the tool's function. It goes further by adding ownership scope ('you can only cancel your own subscriptions'), which distinguishes it from generic cancellation tools and aligns with the sibling context of subscribe/list_subscriptions.

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

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

The ownership enforcement statement provides clear context on when this tool can be used (only for subscriptions belonging to the caller). It does not explicitly name alternatives or state when-not-to-use, but the 'deactivated (not deleted)' clause implies it is the safe cancellation method when historical events must be preserved. The context is clear, though exclusions are not fully spelled out.

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 goes well beyond this by explaining the two verification paths, the exact verdicts, and the critical nuance that could_not_verify means the check did not happen and must not be treated as evidence. This adds substantial behavioral context beyond structured metadata.

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

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

The description is long but every sentence earns its place: it front-loads user intents, explains the two pipelines, lists verdicts, highlights the error semantics, and ends with the benefit of replacing 4–6 calls. The structure is clear with an important callout, though slightly verbose for a tool with only 2 parameters.

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 fully defines the return values (six verdicts, actual value with citation, reasoning) and edge-case behaviors (could_not_verify vs unsupported). For a 2-parameter tool this is thorough and leaves no obvious gaps in what the 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 covers both parameters at 100%, but the description enriches them by mentioning 'exact percent-delta math' for structured claims and tying tolerance_pct to hallucination detection (e.g., 'set 1–2 for hallucination detection'). This explains how the parameters affect the grading process rather than just their syntax.

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 natural-language user phrasings ('Is it true that…'), then states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling research/QA tools by framing itself as a verdict-returning claim checker that replaces sequential calls.

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 tells the agent when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides a decision rule between the SEC EDGAR fast path for company-financial claims and the grounded pipeline for other claims. No explicit alternatives are named, but the context is clear and excludes other use cases.

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