Arcgis Kansas

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b) is free, passing _apiKey opts into paid Anthropic calls ('you pay Anthropic directly'), and it discloses the exact return shape (per-model {score, confidence, signals, raw_response} + combined view). No contradiction found.

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

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

Four sentences, each carrying essential information: purpose, operational details (default model, cost, return fields), and use cases. The description is front-loaded with the primary purpose and contains zero filler words.

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

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

Despite having no output schema, the description enumerates the return fields (score, confidence, signals, raw_response, combined view) and explains how to enable Anthropic. Combined with the 100% schema coverage, an agent has all necessary information to select and invoke the tool correctly.

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

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

Schema coverage is 100% (all 4 parameters have descriptions), so the baseline is 3. The description reinforces that _apiKey is for enabling Anthropic and that the default model is workers-ai, but it does not add new parameter behavior beyond what the schema already documents. The added nuance about the free default is minor.

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

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

The description opens with a specific verb ('Probe') targeting LLMs' knowledge of a business/brand/product/topic, and clearly defines the output (a 0-100 visibility score per model). This distinguishes it from sibling tools like ask_pipeworx or deep_research by focusing on cross-model visibility scoring rather than answering questions 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?

Explicitly lists concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to invoke the tool. It does not name alternative tools or explicitly say when not to use it, but the stated use cases are sufficient guidance for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds meaningful behavioral context: it routes automatically, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss edge cases like source unavailability or fallback behavior, but given the strong annotation coverage, the behavioral picture is largely transparent.

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 front-loads the most critical decision ('PREFER OVER WEB SEARCH'), then moves from supported domains to trigger phrases, examples, and alternatives. It earns its length, though a few phrases are mildly redundant with the opening directive.

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

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

Despite having no output schema, the description specifies the return shape (structured answer with stable pipeworx:// citation URIs), enumerates supported data domains, gives example queries, and names the relevant alternatives. For a routing tool with this much scope and this many sibling variants, the description is complete enough for an agent to invoke it confidently.

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 every parameter is documented as an alias for 'question'. The description reinforces natural-language input and provides examples, but it does not add parameter semantics beyond what the schema already states, so the baseline 3 applies.

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

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

The description opens with a clear directive ('PREFER OVER WEB SEARCH') and explains that the tool routes questions to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. This clearly identifies it as a meta search/router for authoritative data and distinguishes it from alternatives like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit trigger conditions ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete examples, and explicit exclusions ('for one-shot... use ask_pipeworx_grounded; for broad/multi-part... use deep_research'). It even covers news-specific routing, leaving little ambiguity about when to use this tool versus alternatives.

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

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

The description goes well beyond the annotations by explaining live candidate routing, the current inactive candidate status, equivalence to ask_pipeworx, and the lack of fallback. This is exactly the behavioral caveat an agent needs before invoking an experimental variant.

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

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

The description is front-loaded with the beta/router identity and every sentence adds meaningful context. It is slightly verbose with the specific retirement date and the emphatic no-fallback clarification, but both details are relevant.

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 beta router with no output schema, the description covers current behavior, transparency, usage, and parameter equivalence. It relies on ask_pipeworx to define the response shape, but given that sibling is available and the tool is explicitly identical, this 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?

Schema coverage is 100%, and the input schema already documents the question parameter and all aliases. The description only says 'same arguments' and adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description clearly identifies ask_pipeworx_beta as the beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. This gives a specific role and distinguishes it from the stable ask_pipeworx sibling.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, which provides a clear selection condition and names the stable router as the comparison point. It does not spell out when not to use it, but the beta-vs-stable framing makes the intended context clear.

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

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

Annotations only convey read-only, open-world, idempotent, non-destructive traits. The description adds substantial behavioral context: refusal modes with exact refusal_reason values, verbatim evidence extraction, return shape, fetched_at, one extra LLM call cost, and strict no-invention behavior. This goes well beyond the annotations.

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

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

Dense but well-organized: purpose first, then behavior/return/refusal contract, then usage guidance and cost tradeoff. Every sentence carries decision-relevant information; the routing scale detail supports the grounding claim without being 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?

Complete for an agent to invoke correctly: it explains success and refusal return shapes, refusal reasons, when the tool is appropriate, when to prefer the cheaper sibling, and the cost tradeoff. With no output schema, the explicit return contract fills the gap; annotations cover safety and idempotency.

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 thoroughly documents the question parameter plus its five aliases, so the description does not need to repeat parameter details. The description does reinforce that the question drives tool selection and grounding, but adds little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific, differentiated purpose: a hallucination-resistant answer mode that extracts answers only from fetched tool results, distinct from sibling ask_pipeworx and ask_pipeworx_beta. The description names the routing behavior, grounding constraint, and output contract, making the tool's role 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?

Explicitly says when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups') because of the extra LLM call cost. This gives clear selection criteria against 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?

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing internal behavior: fan-out to parallel sources, resolver confidence scoring, low-confidence short-circuiting, closed-market status, wide-spread liquidity warnings, fallback handling for GDELT 429s, and cancellation-rule parsing. It even warns about a recurring pure-rules loss from flat-50¢ voids, which is critical behavioral context.

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

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

The description is long but exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded with the core purpose. Each sentence adds operational detail; while it could be trimmed, the density is justified for a complex research tool.

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

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

There is no output schema, so the description must fully explain return values and edge cases. It covers result.market, result.analysis, result.evidence, resolver contract fields, parent_event extraction, news fallback fields, status codes for low-confidence and closed markets, and cancellation-rule risk. This is as complete as needed for an AI agent to trust and correctly invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by showing concrete examples for 'market' (slug, URL, question text) and clarifying the trade-offs of 'include_raw' (response size vs. full payloads). It doesn't substantially extend beyond the schema, but the examples and usage context justify a 4.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool from siblings like polymarket_edges or polymarket_arbitrage by focusing on single-bet research with category-specific data fan-out.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives actionable guidance on when to check cancellation rules before sizing and explains blocking behaviors for low-confidence or closed markets, effectively telling the agent when the tool is and isn't appropriate.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses detailed behavioral traits: it pulls specific data sources (SEC EDGAR/XBRL, FAERS, FDA), handles off-calendar fiscal years correctly, sorts results by the primary metric so 'largest' reads off the top, and returns paired data with citation URIs. This goes far beyond what annotations provide and sets clear expectations.

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

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

The description is dense but every sentence serves a purpose: trigger phrases, explicit preference, data source details, fiscal-year handling, sorting behavior, and output format. It is front-loaded with usage examples and avoids any fluff or repetition. The structure flows from use case to mechanics to output, making it highly scannable.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description is remarkably complete: it explains what data is returned (paired data + citation URIs), how results are ordered, which data sources are used, and why it is efficient. There are no obvious gaps; an agent would know exactly what happens when invoking 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?

Although the schema already describes both parameters, the description adds substantial meaning: it explains that type='company' retrieves 10-K revenue/net income/cash/debt, type='drug' retrieves FAERS/FDA counts, and gives concrete value examples like ["AAPL","MSFT"]. This enriches the schema definitions by clarifying what data each entity type yields and the expected input format.

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

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

The description uses the specific verb 'compare' with defined entity types ('companies or drugs'), cites exact trigger phrases, and explicitly frames it as a side-by-side comparison in one parallel call. It distinguishes itself from sibling tools by stating it is 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8–15 sequential lookups, making its unique role clear.

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

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

Provides explicit when-to-use guidance through natural-language examples ('X vs Y', 'rank these companies') and states a clear preference over sequential lookups when comparing entities. It also differentiates between 'company' and 'drug' modes, giving context for each, though it does not name a specific alternative tool by section. The instruction to prefer it is strong and actionable.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive; the description adds account/payment requirements, parallel decomposition across 5,798 tools, findings-packet shape with gaps[], contradictions[], hop field, stable citation URIs, semantic excerpting, and expected latency. No conflicts 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?

Long but dense; every sentence earns its place, and the most actionable info (account requirement and fallback tool) is front-loaded. The parenthetical examples and latency expectations compress a lot of behavior into readable prose.

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 specifying return shape (evidence, confidence, source, fetched_at, citation URI, gaps, contradictions), how records are excerpted, and timing. An agent has enough to select and invoke it correctly with no hidden surprises.

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, but the description adds decision-relevant detail: depth:'thorough' requires a paid plan and drives a follow-up hop, and question semantics are clarified as broad natural-language decomposition. This is above baseline yet not a full replacement for the schema's own detailed depth 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?

States a specific, unique function: grounded research across Pipeworx's 1,517 structured data sources in one call, explicitly distinguishing itself from open-web search and sibling ask_pipeworx. The verb plus resource, scope, and decomposition behavior are precise.

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?

Gives explicit routing guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or current-news topics, and use ask_pipeworx when not signed in. Names alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds useful behavioral detail about the return format (top-N most relevant tools with names, descriptions, and full input schemas, ready to call directly) and mentions no second schema lookup is needed, which goes beyond the annotations.

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

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

The description is appropriately sized for a meta-tool that needs to convey both its purpose and its coverage. It is front-loaded with the core purpose, then lists supported domains, then explains the return format and usage timing. While the domain list is long, it is concrete and helps the agent decide when to use the tool. Every sentence contributes value.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (top-N tools with names, descriptions, full schemas, and examples) and how to use it (call first, ready to call directly). The schema covers the query parameter and aliases, and the description provides enough behavioral context for an agent to invoke it correctly. Fully complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the schema already explains all six parameters, including query aliases and limit. The description adds no new parameter-level meaning beyond the schema; its mention of 'top-N' refers to the limit parameter but does not provide additional semantic detail beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It goes beyond a tautology by specifying the resource (tools) and the action (discover/browse/search). It distinguishes itself from sibling data tools by explicitly describing its meta-role of returning tool names, descriptions, and schemas.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly signals when to use the tool versus directly querying a specific data tool.

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

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

Goes well beyond readOnlyHint/idempotentHint by revealing fan-out across many sources, soft-fail behavior for USPTO, empty-section-means-no-data semantics, private-company resolved:false behavior, and resolved_from/resolved_to handling. This is rich, non-obvious behavioral detail.

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

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

The description is long but front-loaded with user triggers and uses dense semicolon-separated result details instead of bullet bloat. Every major behavior earns its place, though some examples repeat schema content and could be tightened.

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

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

Given the tool's multi-source fan-out and the absence of an output schema, the description admirably enumerates every returned block, URI format, and failure mode including real-no-data vs bug and private-company behavior. An agent has enough to call and interpret the result correctly.

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

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

Schema coverage is 100%, and the description largely restates the schema's ticker/CIK/name guidance and type interchangeability. It adds illustrative examples and notes about name resolution, but does not materially define new parameter 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?

Description opens with concrete user intents ('Tell me about X' / 'research Acme' / 'brief me on Tesla') and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call.' This clearly distinguishes it from narrower single-purpose lookups and makes its resource and outcome 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?

States an explicit preference: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which gives clear trigger conditions and what not to do. It does not explicitly differentiate from broader sibling research/comparison tools, so there is a small gap.

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 readOnlyHint=false, and the description reinforces the destructive nature by stating 'Delete'. It adds context about the purpose (clearing stale or sensitive data) and the key-based targeting, which is useful beyond annotations. No contradiction with annotations.

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

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

The description is three short sentences, each contributing distinct value: what it does, when to use it, and how it relates to sibling tools. No redundancy or unnecessary 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 delete tool with strong annotations and full schema coverage, the description fully covers purpose, usage contexts, and relationships to related tools. It 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 description coverage is 100%, so the description adds little beyond what the schema already documents. The phrase 'by key' mirrors the schema's 'Memory key to delete' without adding additional semantic detail. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Delete'), a clear resource ('previously stored memory'), and a precise scope ('by key'). It clearly distinguishes from sibling tools like remember and recall, which are storage and retrieval operations respectively.

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

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

The description provides explicit when-to-use scenarios ('context is stale, the task is done, or you want to clear sensitive data') and names related tools to pair with ('remember and recall'). It lacks explicit when-not-to-use exclusions, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds process details: 'Fetches the page, extracts title/description/key links' and output format as a 'single text blob', enhancing transparency beyond 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?

The description is three sentences, each serving a purpose: what it does, how it does it, and when to use it. It is front-loaded with the primary function and avoids unnecessary redundancy, though the use-case list makes it slightly longer than the leanest examples.

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

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

With only 2 parameters and no output schema, the description covers the necessary ground: process, output format ('ready to drop at site-root/llms.txt'), and use cases. It does not mention error handling or edge cases, but for a simple generation tool, this is adequate.

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 'url' and 'max_links' well-described (including default and max values). The description itself doesn't add parameter-specific meaning beyond what the schema provides, 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 clearly states a specific verb ('Generate') and resource ('llms.txt file'), and elaborates on the process: fetches the page, extracts key info, and emits standard markdown. This distinguishes it from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence', which have different purposes.

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 includes a 'Useful for' section with three concrete use cases (client sites, own project, competitor audit), giving clear context on when to use it. It does not explicitly mention alternatives or when-not-to-use, but the unique purpose renders that less critical.

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 the safety profile is covered. The description adds value by specifying exactly what the tool returns (fields, geometry type, record count, capabilities), giving the agent a clear picture of call results 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 a single, front-loaded sentence that immediately states the action and resource. It lists all key return elements without extraneous words or repetition.

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

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

Given the tool's simplicity (one parameter, strong annotations, no output schema), the description fully conveys purpose and return contents. The listed items (fields, geometry type, record count, capabilities) serve as an adequate return contract for the agent.

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

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

Schema description coverage is 100% and the only parameter 'url' is already documented in the schema. The description adds no further semantic detail beyond restating 'by url', so it does not exceed the baseline for well-documented schemas.

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 uses specific verb 'Get' and names the exact resource (ArcGIS Feature/Map Service layer's schema), listing returned items (fields, geometry type, record count, capabilities). This clearly distinguishes it from sibling tools like query_layer, which likely queries 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 the tool is for retrieving layer schema but offers no explicit guidance on when to use it vs alternatives. It does not mention query_layer or any when-not-to-use conditions, leaving usage to inference.

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 indicate read-only, idempotent, non-destructive. The description adds value by enumerating return fields and clarifying the default behavior (active subscriptions only, with inactive included only via parameter). 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?

Two sentences, zero filler. The first sentence states the action and return fields; the second sentence gives practical usage context. Every word contributes to understanding.

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

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

For a simple list tool with one optional parameter, full schema coverage, and strong annotations, the description provides all needed information: purpose, scope, return fields, and usage cues. No output schema is needed because return fields are listed.

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

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

The schema description covers the parameter fully (include_inactive with default false). The tool description does not introduce additional parameter semantics beyond the schema, though it reinforces the default by saying 'active subscriptions'.

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 action (list) on a specific resource (the caller's active subscriptions) and lists the returned fields. It distinguishes this from sibling tools like subscribe and unsubscribe by focusing on review/listing rather than mutation.

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: 'review what you're monitoring before adding more' and 'find an id to cancel'. It does not name sibling tools subscribe/unsubscribe directly but clearly implies when to use this tool relative to those actions.

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 rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and behavioral workflow (filing without an account returns a claim_token that can be reused to check status). Annotations are all false and do not contradict this; the description adds rich context beyond the structured fields.

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

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

The description is dense but well-structured, front-loading the core purpose before covering usage, constraints, and follow-up. Every sentence provides necessary information, but the length and punctuation make it slightly harder to parse than an ideal concise description.

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 (4 params, nested object, no required parameters, no output schema), the description fully explains return values (claim_token, later status), rate limits, scope, and intent. It leaves no critical gap for an agent to misuse the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful workflow context, particularly for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and for message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It exceeds the baseline but doesn't fully elaborate on context object fields.

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

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

The description clearly defines the tool as 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools by stating it is ONLY for tools served by this Pipeworx connection, contrasting with other MCP servers.

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

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

Provides explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives exclusion guidance for tools from other servers and instructs to file with that server instead, plus explains using claim_token for follow-up.

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

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

Beyond the readOnly/idempotent annotations, the description reveals that data is derived from CF analytics-engine, contains no PII, exposes only (pack, tool, count) tuples, and is cached 5min-1h depending on window. These are meaningful behavioral details that shape expectations.

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

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

The description is compact yet information-dense: it leads with the core value proposition, follows with a scannable numbered use-case list, and closes with essential notes on data source and caching. Every sentence contributes useful content without redundancy.

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

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

Despite lacking an output schema, the description covers the return shape (pack, tool, count), the data source, privacy guarantees, caching, and practical use cases. For a simple read-only tool with one optional enum parameter, this is complete.

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

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

The only parameter 'window' is fully described in the schema with enum values, a default, and guidance on shorter vs longer windows. The description restates the window options but adds no further parameter-level meaning, so the baseline of 3 applies given 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?

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from sibling tools by focusing on aggregate usage trends ('what other AI agents are calling') rather than generic discovery or search.

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

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

A 'Useful for' list provides three concrete scenarios: discovering hot data sources, confirming a canonical tool choice, and checking alignment with agent needs. It does not explicitly name alternative tools or state when not to use it, but the clear context is enough for an agent to decide.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses algorithmic details: Jaccard similarity threshold (≥0.30), placeholder filter (>20% returns null), fill-check behavior against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. This gives the agent full transparency about the tool's internal decision logic.

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

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

The description is long (around 250 words) but uses structured section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Every sentence adds relevant detail for a complex tool, though it could be slightly tightened without losing value.

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

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

With no output schema, the description explicitly documents the response shape (opportunities[] with fields, partition_check object) and edge cases (placeholder filters, low-similarity rejection, fill-check results). It covers the tool's modes and failure conditions, though it doesn't specify behavior when both arguments are passed or error handling, which is a minor gap.

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

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

Although the input schema already describes each parameter, the tool description adds significant context: event is 'recommended for a specific market' with slug/URL examples, topic is for cross-event scanning with seed question examples, and the difference between them is explained in depth. This goes well beyond the schema's short 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-object pair ('Find arbitrage opportunities on Polymarket') and names the detection methods (monotonicity violations + partition-sum checks). It then details three invocation modes (trending_scan, event, topic), which clearly distinguishes it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, `event` for a specific market, `topic` for cross-event scanning. It also directs users to polymarket_fill_risk for custom sizing, naming an alternative tool, and explains the recommended mode for each scenario.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses substantial behavioral context: model families, response segmentation, the 24h-move warning, Fed-bet exclusion rationale, caching behavior, and diagnostic counters for empty segments. It even warns that 'your edge may already be in the price,' providing valuable execution caveats.

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 extremely long and dense, with numerous clauses, nested explanations, and technical details (e.g., per-sport alpha values, gate relaxation parameters). While it is organized, it is far from concise and would be difficult for an agent to parse quickly. Not every sentence earns its place in a high-level description.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), parameter effects, and reasons for empty segments. It also covers edge cases like placeholder slugs and partition filters, making it effectively complete for a tool of this complexity.

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

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

The input schema already has 100% coverage with detailed descriptions for all 9 parameters, including examples and rationale. The description adds conceptual grouping (e.g., 'TRADEABLE-EDGE KNOBS') but does not significantly expand on the schema's parameter semantics, 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 opens with a specific verb+resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's function and distinguishes it from siblings by referencing Pipeworx data and the scope of 'top markets' rather than all markets.

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

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

The description explicitly frames the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear context for when to use the tool, though it does not name alternative tools or provide explicit 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals the tool reads from snapshots written on cache-miss, so gaps in snapshot_dates mean no scan occurred. It also discloses that decay is computed from daily closes of edge_pp_net (not intraday) and that history depth is bounded by a 60-day TTL. This goes well beyond the annotations, providing critical behavioral context.

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

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

The description is dense but well-structured with clear sections (Args, RESPONSE, LIMITS). Every sentence carries useful information about response format, edge cases, and limitations. It's longer than average but 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 response structure is fully described: tracked[] with time-series, trend, decay rate, expired[] with lifespan, and snapshot_dates[] with gap semantics. The description also explains the signed edge_pp_net (negative = SELL YES) and the median lifespan as a 'competition clock'. Given no output schema, this description compensates admirably.

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 full descriptions for both days and window, so the base is covered (coverage 100%). The description adds the clamp ranges (2-30) and default values, but these are also in the schema. The window parameter is described as 'snapshot family' which adds a slight semantic nuance, but overall the description adds minimal extra value beyond the schema.

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

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

The description clearly defines the tool as 'edge persistence and decay telemetry' built from daily snapshots, answering a specific temporal question about edge aging. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trend (persistence/decay) rather than current edge values. This provides a specific verb-resource pair and differentiates the tool.

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

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

The description provides a clear use case: answering 'how long has this edge existed and is it shrinking?', and even explains the trading implication (fresh vs 3-week-old edges are different). It doesn't explicitly name alternative tools for when not to use it, but the context makes it clear this is for temporal analysis, not current edge discovery. The LIMITS section also warns about data gaps and TTL, which helps set expectations.

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

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

The description goes beyond the annotations (readOnlyHint=true, etc.) by detailing what the tool returns, including verdicts (clean|degraded|cannot_fill), slippage, and risk indicators like forced_directional_risk. It also explains the practical implication of partial fills in basket mode, adding valuable behavioral context. There is no contradiction with the annotations, which declare the tool read-only, and the description consistently frames it as a check rather than an execution.

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

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

The description is long and dense, but it is well-structured with clear segments (SINGLE-MARKET, BASKET, USE THIS). The first sentence front-loads the core purpose. While every sentence carries useful information, some redundancy with the schema (e.g., defaults and clamps) slightly reduces conciseness. Overall, it is appropriately sized for a complex two-mode tool.

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

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

The description is comprehensive: it covers both modes, all parameter semantics, return values in detail (top_of_book, vwap_fill_price, slippage_pp, etc.), usage guidance, and risk implications. Since there is no output schema, the description fully fulfills the burden of explaining what the agent will receive. It also explicitly ties to sibling tools and sets thresholds, making it complete in context.

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

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

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds strategic meaning beyond schema, such as interpreting side auto behavior in basket mode (sell if partition sum > 1, buy if < 1) and explaining size_usd as settlement notional in basket mode (shares per leg, each paying $1). This enriches the agent's understanding of how to set parameters for intent.

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 statement: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then details two distinct modes (single-market and basket) with specific inputs and outputs, making it clearly distinct from sibling tools like polymarket_arbitrage and polymarket_edges. The verb 'check' and resource 'edge' against order-book depth precisely define the tool's function.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical overround and warns about partial basket fills leading to unhedged directional positions. This directly addresses alternatives and timing, which is exemplary.

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 signal readOnlyHint, idempotentHint, and openWorldHint, and the description goes far beyond that by disclosing matching behavior: token-overlap matching, compatibility codes, unclassified legs never being paired, skipped-cross counters, gross-vs-net fee treatment, and the caveat that returned pairs may still carry warnings. This gives the agent a realistic model of what the tool will and will not do.

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

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

The description is long but densely packed and clearly structured with uppercase labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. Some information is repeated for emphasis, such as temporal_alignment_unknown appearing both in the codes list and the temporal_alignment explanation, but the repetition serves safety-critical clarity. It is not concise, yet every sentence contributes useful operational knowledge.

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

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

With no output schema, the description carries the full burden of explaining the response shape, and it does so thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, compatibility_codes[], per-leg flags, skipped-unclassified pairs, low_confidence_pairs, temporal_alignment, and fees_note. It also tells the agent to read warnings even when matched_pairs>0, which is exactly the kind of conditional guidance needed 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 schema already documents all three parameters at 100% coverage, but the description adds meaningful interaction semantics: topic shortcuts auto-fetch matching events, explicit ticker/slug values override the mapped side, and both modes run the same matcher. It also lists the valid topic values in the description, reinforcing the schema. A 4 is appropriate because the added semantics go beyond the property descriptions without introducing new syntax requirements.

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 statement: compute the cross-venue spread between Kalshi and Polymarket for the same resolving question. It additionally distinguishes itself from tradeable-arbitrage tools by explicitly labeling the spread as gross and not a net tradeable edge, which differentiates it from sibling polymarket_arbitrage without needing to name it.

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 two operation modes are clearly explained: use a pre-mapped topic shortcut or supply explicit kalshi_event_ticker and polymarket_event_slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable, giving practical usage expectations. It does not explicitly name sibling alternatives, but the context is clear enough.

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, non-destructive, and open world. The description adds that it 'Returns attribute rows (and geometry)', which is useful behavioral info beyond the annotations. No contradiction with annotations.

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

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

Two sentences, no fluff. The description is front-loaded with the core action and then packs useful parameter and usage details. 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?

With 6 parameters, 100% schema coverage, and a clear URL source, the description covers the essential usage: what it queries, key parameters, return type, and a sampling recipe. No output schema exists, but the description mentions the return type (attribute rows and geometry). Missing minor details like error handling, but sufficient for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing parameters as 'SQL-like' and providing a concrete usage pattern ('where="1=1" + out_fields="*"') for sampling, which goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url', naming a specific verb and resource. It distinguishes itself from siblings by linking to search_datasets for the URL and listing its core query parameters.

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 by noting the URL comes from search_datasets and offers a concrete sampling tip ('Use where="1=1" + out_fields="*"'). It doesn't explicitly exclude alternatives like layer_info, but the usage context is reasonably 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 and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations, particularly the scoping behavior ('Scoped to your identifier') and the listing behavior when omitting the key. It doesn't over-describe but provides meaningful operational detail.

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, front-loaded with the primary purpose, and structured logically: retrieve/list, use case, scoping, and complementary tools. No filler or redundancy; every sentence earns its place.

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

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

For a simple tool with one optional parameter, the description fully covers usage, scope, and context. The schema and annotations handle parameter definitions and safety hints, so the description completes the picture without needing return-value details or additional warnings.

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

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

The schema already documents the sole 'key' parameter with 100% coverage, including the omit-to-list behavior. The description reinforces this but doesn't add new parameter-level semantics beyond what the schema provides, 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 states the tool's core action with a specific verb ('retrieve') and resource ('value previously saved via remember'), and clearly distinguishes the optional list-all behavior. It also separates itself from siblings by explicitly naming 'remember' and 'forget', eliminating ambiguity.

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 to look up context the agent stored earlier...') and names the complementary alternatives ('Pair with remember to save, forget to delete'). This gives the agent a clear decision framework.

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?

Annotation Contradiction: The tool is marked readOnlyHint=true, but the description states setting mark_read:true 'flag returned events read so the next call only shows newer ones' — a state-changing side effect. This directly contradicts the read-only annotation. Despite the description being transparent about the behavior, the contradiction warrants a score of 1 per the rubric.

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

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

Four sentences, front-loaded with the core function, no redundancy. Each sentence contributes either return-shape details, filtering options, state-mutation semantics, or a direct link alternative. Properly sized for the tool's complexity.

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

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

The description covers return shape, filtering, state mutation, polling suitability, and an external endpoint. For a tool with 5 optional parameters and no output schema, this provides comprehensive context for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete example for type ('sec_8k'), clarifying the 'since' format (ISO timestamp), and explaining the effect of mark_read on subsequent calls. This enriches the bare schema definitions.

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

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

The description opens with 'Pull fired events from your subscription feed', which is a specific verb+resource pairing. It clearly states the tool returns the most recent alerts with detailed payload attributes, distinguishing it from siblings like list_subscriptions (which lists subscriptions, not events) and recent_changes.

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

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

It provides concrete usage context: filtering by type (e.g., 'sec_8k') and since (ISO timestamp), mark_read behavior for pagination-like reading, and even an alternative endpoint for scripts/dashboards. While it doesn't explicitly name sibling tools to avoid, it gives clear scenarios and alternatives.

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

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

Despite annotations already marking readOnly/idempotent/destructive hints, the description adds rich behavioral detail: fan-out to multiple external APIs, GDELT→GNews fallback on rate-limit/5xx, PatentsView API sunset causing soft-fail, and return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). This goes well beyond what annotations provide.

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

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

The description is information-dense yet well-structured: examples, core purpose, sources, parameter format, return format, and alternative usage. Every sentence earns its place, front-loading natural-language triggers. Despite its length, it avoids redundancy and flows logically.

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

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

Given three parameters, no output schema, and a complex multi-source aggregation tool, the description covers all essential context: sources, fallback behavior, failure modes, return shape, and alternative tools. Even the `since` parameter's accepted formats are explained. This is a complete description for selecting and invoking the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the `since` format (ISO date or relative) and `value` as ticker/CIK, but the schema already provides these details with examples. No new parameter semantics are added beyond the schema, so it neither improves nor degrades the baseline.

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

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

The description clearly states the tool's specific purpose: 'change feed for a company in the last N days/weeks/months'. It lists concrete sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes itself from sibling tool entity_profile: 'Use entity_profile instead when you want the static profile'. This is a specific verb+resource with strong sibling differentiation.

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 opens with natural-language queries ('What's new with X', 'latest on Y') to signal when to use it. It explicitly provides an alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This satisfies the when/when-not/alternatives criterion with 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 adds valuable behavior not in annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours, and data is stored as key-value pairs. This goes beyond the annotations' idempotentHint and destructiveHint.

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

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

Four sentences, each earning its place: purpose, usage context, storage details, and relationship to recall/forget. No redundant words, and the most critical information is 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?

For a simple two-parameter save tool with full schema coverage and no output schema, the description provides sufficient context: it explains persistence, scoping, lifetime, and integration with siblings. It's complete for the agent to invoke correctly.

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

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

Schema coverage is 100%, and the description reinforces the meaning of key and value with examples (e.g., 'subject_property', 'target_ticker') and clarifies that value can be any text. While not adding new parameter names, it enriches the semantics with practical use cases.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb ('Save') and resource ('data'). It provides concrete examples like 'resolved ticker' and 'target address', and distinguishes itself from siblings by mentioning recall and forget as complementary tools.

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

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

It explicitly states when to use: when you discover something worth carrying forward. It also gives alternatives (recall, forget) and context about persistence for authenticated vs anonymous sessions, helping the agent decide when this tool is appropriate.

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

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

Beyond annotations that mark the tool read-only and idempotent, the description discloses meaningful behaviors: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-name handling via figi_candidates, explicit reporting of unresolved identifiers, source-labelling, and internal multi-endpoint cascading. No contradiction with annotations exists.

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

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

The description is front-loaded with user-like examples and an explicit 'Use FIRST' directive. It is dense and contains long parenthetical asides, but nearly every clause adds necessary behavioral or semantic detail, so the length is justified even if not perfectly 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?

There is no output schema, so the description compensates by explaining what identifiers are returned, how ambiguity is represented, what happens when external sources fail, and what input formats are accepted. An agent has enough information to invoke the tool correctly and interpret its likely 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 significantly enriches parameter meaning: 'company' resolves across EDGAR/GLEIF/OpenFIGI, 'drug' maps to RxNorm RxCUI, ISIN inputs resolve to legal entities via LEI, and value guidance explains why only the issuer name should be passed for bonds. These details go well beyond the schema's basic descriptions.

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

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

The description defines a specific action—resolving a user-spoken name to canonical/official identifiers—and lists the concrete outputs (CIK, ticker, LEI, FIGI, RxCUI). It also distinguishes the tool from siblings by positioning it as the first lookup when an ID is needed, rather than a profiling or comparison tool.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also covers important sub-cases like bonds and drugs. However, it does not explicitly state when not to use this tool or name a specific alternative, so it falls slightly short of a complete routing rule.

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

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

With annotations already declaring readOnly, openWorld, idempotent, and non-destructive, the description adds valuable behavioral context: it internally calls ai_visibility_check multiple times, ranks results, and returns a specific structure (score, confidence, signal density). It does not discuss performance/cost implications, but with annotation coverage this is a strong score.

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, front-loaded with the primary action, and each sentence serves a purpose: function, process, use case, and return format. There is no fluff 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?

Given no output schema, the description still explains the return format ('ranked list with score, confidence, signal density'). It also clarifies it compares multiple entities and uses ai_visibility_check. It could mention edge cases or call costs, but for a read-only tool with good annotations, this is nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add semantic meaning beyond the schema; it merely references the parameters without new details. The entities parameter's 'first entry as subject' nuance is already in the schema description, so no extra value is provided.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and explains the process ('Probes each entity... with ai_visibility_check, ranks by score'). It distinguishes itself from the single-entity sibling ai_visibility_check and the generic compare_entities by focusing specifically on AI visibility comparison across competitors.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' with a concrete example question. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks the full 'when-not/alternatives' guidance required 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond annotations: timing (bundlephobia's first measurement can take 5-30s), graceful partial failure behavior (sources_failed lists timeouts), and the ecosystem scope limitation. This is more than the annotation baseline, though it could mention rate limits or data freshness.

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

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

A single dense paragraph, front-loaded with the core composite check, then usage triggers, return fields, and limitations. Every sentence carries unique information (sources, use cases, output summary, failure behavior, ecosystem boundary). Slightly long, but no redundancy; the structure is logical and efficient for the tool's complexity.

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

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

Given no output schema, the description fully compensates by enumerating the exact return block (is_latest, license, bundle_kb_min, etc.), advisory details, links, and alternative versions. It also covers multi-source behavior, the 5-30s timing caveat, and how partial failures are reported. No major informational gap remains.

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

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

Schema description coverage is 100%: both 'package' and 'version' have meaningful descriptions. The tool description reinforces the package scope (NPM only) and mentions version default indirectly, but does not add substantive parameter-level semantics beyond the schema. Baseline 3 is appropriate for full schema coverage.

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

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

The description opens with a specific verb-resource pairing: 'Composite should I add this npm package to my project check in ONE call' and names the exact data sources (deps.dev, bundlephobia). It clearly distinguishes itself from sibling tools by focusing on npm dependency scanning with a defined return summary block.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides a clear exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives both 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 declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description's main added value is the specific return fields (name, summary, record_count, owner/org, url) and the type of data (open geospatial datasets). This adds useful context beyond the annotations, though it does not cover rate limits or org_id override behavior.

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

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

The description is two sentences: the first states the core functionality and scope, the second lists return values and directs the user to downstream tools. No wasted words; information density is high and 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 compensates by listing the return fields and the downstream use case. It covers the core functionality and integration, but does not address edge cases like org_id override effects or pagination. This is slightly above adequate given the moderate complexity and strong schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level semantics beyond what the schema already provides, but it reinforces that 'query' is a keyword search and that 'org_id' is an override. This meets the baseline without exceeding it.

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

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

The description clearly states the tool searches Kansas State GIS open geospatial datasets by keyword, with specific examples of dataset types (parcels, zoning, transport). It distinguishes itself from siblings by detailing the return fields and the workflow of passing the 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?

The description provides clear context for use as the discovery step before query_layer/layer_info, implicitly distinguishing it from those tools. It does not explicitly mention when to use it over other search tools, but the workflow 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 already mark it read-only, idempotent, non-destructive. The description goes further by disclosing the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, the 200K char cap, and that longer inputs are truncated and flagged. These are valuable behavioral details 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 compact and front-loaded. It opens with the core purpose, then moves to usage context, then to technical specifics. Every sentence adds value—no fluff or repetition.

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

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

Despite no output schema, the description explains the return format (passages with offsets and similarity scores), the input constraints (200K cap, truncation), and the use case. Combined with full parameter descriptions and strong annotations, it provides a complete picture for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides (e.g., the schema already explains 'text', 'query', and 'limit'). It mentions general concepts like 'character offsets' but does not enhance the meaning of individual parameters.

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

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

The description clearly states it is 'Semantic search INSIDE a fetched record' with a specific verb and resource. It explains the inputs (text + query) and outputs (top-N passages with character offsets and similarity scores), and distinguishes itself from siblings by emphasizing it operates on an already-fetched record, not external data.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a complementary alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and how it relates to a sibling tool.

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

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

Annotations indicate readOnly=false, idempotent=true, destructive=false. The description goes well beyond these by disclosing OAuth requirements, subscription persistence, delivery channel constraints (SMS verification, 10/day cap), webhook signing and auto-disable behavior. This is rich contextual disclosure with no contradiction to 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 structured: purpose, requirement, types, delivery. Each clause adds a constraint or example without filler. While longer than standard one-liners, the length is warranted given the three nested parameters and multiple delivery channels it must cover.

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 value, auth requirements, all supported subscription types with examples, delivery channels with limits and security details. Since there is no output schema, the description sufficiently addresses behavioral and contextual needs for a tool with this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant semantic value by explaining type-specific params (e.g., sec_8k item codes, polymarket topic, fred_series series_id) and delivery constraints beyond the schema's already-detailed field descriptions, justifying a score above baseline.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb+resource that clearly distinguishes from siblings like list_subscriptions and unsubscribe. It also states the return value, the new subscription id, further clarifying the tool's 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 provides clear prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist) and identifies alternative retrieval methods (recent_alerts or registry URL). It does not explicitly contrast with sibling tools, but the context is strong enough to guide when to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent; the description adds that results come from a 'live catalog of thousands of tools', lists output categories, and notes it teaches how to call meta-tools. This goes beyond structured metadata while remaining consistent 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 longer than average but front-loaded with example prompts and a clear purpose, and every sentence contributes functional value. It could be trimmed slightly, but it's well-structured for an onboarding tool.

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

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

With a single optional parameter, no output schema, and rich annotations, the description fully covers what the tool returns (categorized examples with tool+argument shape), how to control scope, and when to invoke it ('FIRST'). No significant gaps.

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

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

The input schema already documents `topic` with a full list of valid values and 'omit for a cross-category spread'. The description only repeats examples like 'finance', 'pharma', 'betting' and 'focus', adding little new meaning. Baseline 3 is appropriate given 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?

The description opens with natural-language prompts, then defines the tool as the 'onboarding entry point' and specifies it returns category-bucketed example questions with the exact tool + argument shape. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

It gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass `topic` vs no arguments. However, it does not explicitly state when not to use it or name alternatives, so it's not a perfect 5.

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

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

Annotations indicate a non-readonly, non-destructive operation. The description adds valuable behavior: ownership enforcement, deactivation instead of deletion, and the preservation of historical events via recent_alerts. This enhances the annotation-provided safety profile 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?

The description is two sentences, front-loaded with the core action, and every clause adds relevant detail (ownership, deactivation, history preservation). No wasted words.

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

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

For a single-parameter tool with rich annotations and no output schema, the description fully covers the operation's effect, constraints, and side effects. It mentions recent_alerts for historical context, making the tool's place in the ecosystem clear.

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 fully documents the single parameter 'id' as 'Subscription id (uuid) returned by subscribe' (100% coverage). The description only says 'by id' and adds no new parameter-level meaning, 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 opens with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes the tool from siblings like subscribe (creation), list_subscriptions (listing), and recent_alerts (viewing historical 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?

The description provides clear context: users can only cancel their own subscriptions, and the row is deactivated rather than deleted. It implicitly directs users to recent_alerts for historical events, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

The description adds substantial behavioral nuance beyond the annotations: it explains verdict types, error semantics, and the critical distinction between could_not_verify (check failed, not evidence) and unsupported (no source found). It also warns callers not to treat could_not_verify as evidence for/against, which is essential for correct agent 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 well-structured: it front-loads trigger phrases, then covers usage, routing, return values, and a critical caller note. Every sentence earns its place, 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?

With no output schema, the description thoroughly covers return values, verdict types, source citation format, error conditions, and the two failure modes. It also explains the tool's efficiency benefit. The agent has all necessary context to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with both parameters thoroughly described (e.g., tolerance_pct range and default). The tool description does not add significant extra parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'natural-language claim verification against authoritative sources' with explicit trigger phrases like 'fact check' and 'verify the claim that...' It distinguishes itself from sibling search/research tools by focusing on producing a verdict for user claims.

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 whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. It also describes routing between financial and non-financial claims. However, it does not explicitly name sibling alternatives for when not to use, 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.