Arcgis Cedarpark

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable context about authentication and cost (BYO Anthropic key, caller pays Anthropic directly) and clarifies the default model behavior, going beyond the structured hints.

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

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

Three sentences with no fluff: purpose, default behavior, return format, and use cases are all covered efficiently. The most important information (what it does) 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?

Even without an output schema, the description explicitly details the per-model and combined return shape ({score, confidence, signals, raw_response}) and addresses cost/auth implications. Combined with 100% schema parameter coverage, an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little context (default model, BYO key cost implications) but largely restates what the schema already documents, so it doesn't substantially enhance parameter understanding.

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 ('Probe') with a clear object (LLMs) and a defined outcome (score visibility 0-100 per model), fully distinguishing this tool from siblings like scan_competitor_ai_presence. It also immediately states the default model and the return shape, leaving no ambiguity about what the tool accomplishes.

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 listed ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and the description explains when to include Anthropic via a BYO key. However, it does not name alternative tools or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint, and the description adds context beyond these: routing across a large tool collection, returning stable pipeworx:// citation URIs, being a single fast call, and working on every tier. It does not contradict any annotation, and the added detail about citations and performance is valuable, though it doesn't discuss error handling or rate limits.

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 it is information-dense and well-structured. It front-loads the most important usage preference and then covers scope, citations, examples, and alternatives. Every section earns its place, though minor tightening of the source-type enumeration could make it slightly more concise.

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

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

With no output schema, the description appropriately states that the return is a 'structured answer with stable pipeworx:// citation URIs,' which covers the main return expectation. It also addresses domain coverage, alternative tools, performance characteristics, and example queries. The only notable gaps are exact response JSON structure and error behavior, but those are partially mitigated by the description's clarity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases clearly. The description adds value beyond that by providing example questions and phrasing patterns ('what is', 'look up', 'get the latest'), which help the agent construct an effective question parameter even if the schema already lists the aliases.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to 5,417 tools across 1,405 sources and returns structured answers with citations. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so there is no ambiguity about what this specific tool does.

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

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

Usage guidance is explicit and comprehensive: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and clear step-up instructions for alternatives like ask_pipeworx_grounded (hallucination-resistant single answers) and deep_research (broad/multi-part questions). It includes concrete trigger phrases and examples, making it easy for an agent to decide when to invoke this tool versus siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds meaningful behavioral context beyond annotations: it states candidate routing improvements are enabled live when under test, that no candidate is currently active, and that this is a full working router. This clarifies the experimental but functional nature of the tool.

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 composed of four purposeful sentences, each addressing a distinct aspect: identity, current state, usage instruction, and operational reassurance. It is compact, front-loaded with the key beta identity, and contains no fluff.

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

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

Given the tool's simplicity (one question parameter) and the absence of an output schema, the description fully covers necessary context: it explains the relationship to ask_pipeworx, current routing status, and that the response shape matches the stable version. The agent has enough information to decide when and how to invoke it.

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

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

The input schema has 100% coverage, explicitly describing 'question' and all aliases. The description adds no extra parameter-level detail, only referencing that arguments match ask_pipeworx. Thus, the schema carries the full burden, and 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 identifies this as a beta version of ask_pipeworx, a universal router with 5,417 tools, and explicitly distinguishes it from the stable ask_pipeworx by noting its experimental edge. The verb 'ask' is implied through the tool name and the phrase 'Use it exactly like ask_pipeworx', making the tool's function unambiguous.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It effectively tells the agent when to prefer this over the stable alternative, fulfilling the requirement for usage 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?

Discloses significant behavioral traits beyond annotations: 'Costs one extra LLM call vs ask_pipeworx', the explicit refusal structure with possible reasons, and the strict extraction method. Annotations only state readOnly/idempotent, so the description adds substantial 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 and slightly long, but every sentence carries meaningful information. The first sentence fronts the core purpose, and the rest adds use cases, cost, and failure modes. The structure is logical, though the run-on sentence about routing could be split for readability.

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

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

Given no output schema, the description fully specifies the return shape on success and failure, including refusal reasons. It covers cost, use cases, and behavioral guarantees, making it complete for an agent to correctly select and 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% for all parameters including aliases, so the description doesn't need to add much. The description mentions 'Your question in natural language' and that aliases are accepted, but this is already in the schema. No additional semantic detail beyond schema coverage.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (EXTRACTS) and resource (tool result). It explicitly distinguishes from the sibling ask_pipeworx by noting the same routing but an extraction step that uses only the tool result.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also gives a clear exclusion and alternative: 'prefer ask_pipeworx for casual lookups.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond that: low-confidence matches short-circuit with status, closed markets skip fan-out, wide spreads carry tradeability flags, and cancellation rules are analyzed with EV impact. It also discloses blocking behavior and potential fallback failures, which is exactly the kind of context an agent needs.

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

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

The description is long but well-structured with section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and front-loaded purpose/use cases. Every major section adds distinct operational detail, but the length is borderline and a few details (e.g., repeated mention of blocking paths) could be 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?

There is no output schema, yet the description documents the response shapes comprehensively: result.market fields, result.analysis with edge/kelly and 24h-move warnings, result.evidence, market_match_confidence with alternatives and suggestions, parent_event data, news fallback fields, and status codes. For a tool of this complexity, the description is thorough enough for an agent to know what to expect and how to react.

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 description largely repeats the parameter details already in the schema (slug/URL/question text, quick vs thorough, include_raw default false and size implications). The description adds examples of fan-out data sources but no new parameter semantics beyond the schema, 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the core workflow (resolve, classify, fan-out, return evidence packet + market-vs-model comparison) and the intended use cases ('should I bet on X', etc.). This distinguishes it from sibling tools like polymarket_edges or deep_research by emphasizing the one-call research and evidence pack behavior.

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

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

Explicit usage guidance is given via 'Use for "should I bet on X"...' and the detailed fan-out examples show when the tool is appropriate. However, it does not name alternatives or explicitly state when NOT to use this tool versus siblings such as polymarket_edges or validate_claim, so it misses the 'when-not' part of a pure 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete behaviors: it fetches specific SEC EDGAR/XBRL fields for companies (revenue, net income, cash, long-term debt), handles off-calendar fiscal years, pulls FAERS and FDA data for drugs, sorts by primary metric, and returns citation URIs. It also notes performance benefits ('ONE parallel call', 'replaces 8–15 sequential lookups'). These are valuable details not present in annotations, with no contradictions.

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

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

The description is dense but every sentence earns its place. It leads with user-facing trigger phrases, states the core action, gives entity-type-specific data details, explains output ordering, and closes with a value proposition. The structure flows logically from usage cues to technical specifics, with 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?

For a tool with only two parameters and no output schema, the description is remarkably complete. It tells the agent exactly what inputs to provide, what data will be returned, how results are ordered, and what citation format to expect. It also positions the tool relative to alternatives (sequential lookups), making it self-contained for invocation decisions.

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 covers parameter names and basic descriptions (100% coverage), the description adds significant semantic meaning. It maps the 'type' enum values to specific datasets and output metrics (10-K data vs. FAERS/FDA counts), explains the 'values' array format with tickers/CIKs vs. drug names, and gives examples. This goes well beyond the schema's minimal descriptions to help the agent choose and format parameters correctly.

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

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

The description opens with concrete example queries and immediately states the core purpose: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This clearly distinguishes it from singleton lookup tools like entity_profile by emphasizing multi-entity comparison. The verb 'compare' plus the resource scope ('companies or drugs') is specific and unambiguous.

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

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

The description provides explicit when-to-use guidance via 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and the trigger phrase examples ('X vs Y', 'rank these companies'). It also implies when not to use it (when not comparing multiple entities) and contrasts against the alternative of sequential lookups. This is strong, actionable guidance.

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

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

While annotations already declare readOnly, openWorld, and idempotent hints, the description adds substantial behavioral context: account/paid-tier requirements, gap handling (returns gaps[] never invents), contradictions[] scan, semantic excerpting, latency expectations, and hop behavior. No contradictions with annotations.

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

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

The description is lengthy but information-dense and well-structured, covering account, alternatives, behavior, and return format. It is front-loaded with critical prerequisites and use-case guidance. Slightly verbose but every sentence serves a purpose for such a complex 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?

Given no output schema, the description fully details the findings packet structure, gap/contradiction fields, hopping behavior, and latency. It also explains the tool's limitations (e.g., returns empty gaps for news topics), making it highly complete for an agent 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 coverage is 100%, so baseline is 3. The description reinforces depth semantics (quick/standard/thorough) and adds guidance on question phrasing ('Broad/multi-part is fine — decomposition is the point'), providing useful context beyond the schema descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources in one call, explicitly distinguishing it from open-web search. It also contrasts with ask_pipeworx for single lookups, making the tool's purpose and scope unambiguous.

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

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

Provides explicit guidance on when to use this tool (broad/multi-part questions over structured data) and when to prefer ask_pipeworx (single lookups, breaking news, user not signed in). Also explains depth-level tradeoffs and account requirements, covering both alternatives and exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it returns top-N tools with names, descriptions, and full input schemas, ready to call directly, eliminating a second schema lookup. This explains the output format and the tool's meta-nature, which is not provided by annotations.

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

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

The description is structured with a clear opening statement, usage guidance, return behavior, and a strong recommendation. The domain list is lengthy but provides concrete value by enumerating covered topics. Each sentence contributes meaningful information; it's not overly verbose or repetitive given its informative density.

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

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

The tool has no output schema, so the description's explanation of the return format ('Returns the top-N most relevant tools with names, descriptions, and full input schemas') is essential and provided. It covers purpose, usage, return behavior, and examples are in the schema. It doesn't mention pagination or error cases, but for a read-only discovery tool, the description is sufficiently complete with strong annotations supporting 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 description coverage is 100%: all six parameters (query, q, task, limit, search, description) have clear descriptions in the schema. The description text adds little beyond the schema's param documentation; it mentions 'top-N relevant tools' but does not explain the limit parameter or add new semantic details. 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 lists many specific domains (SEC filings, FDA drugs, etc.), giving a concrete sense of what it covers. It also distinguishes itself from siblings by explicitly stating 'Call this FIRST when you have many tools available' and by noting it returns schemas ready to call, which no sibling description does.

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

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

The description 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 tells the agent when to use this tool and implies when not to (when you already know the exact 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, and non-destructive hints. The description adds valuable behavioral context: the tool fans out across multiple sources in one parallel call, includes a patents API sunset with soft-fail behavior, and a news fallback chain (GDELT→GNews). This goes 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 long but front-loaded with examples and a clear purpose statement. It includes a bulleted-like list of return fields and explicit fallback notes. While the example list is extensive, every phrase adds utility for pattern matching. It is well-structured and not redundant.

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

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

For a complex tool with multiple data sources, the description is remarkably complete. It specifies input constraints, return fields (including sorting for fundamentals), fallback behavior, and a limitation (patents API soft-fail). No output schema exists, so the detailed return list is essential and fully supplied.

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 description largely restates the schema's parameter meaning (ticker/CIK, names not supported). It adds a bit of context by emphasizing the identifier formats, but the schema already covers these details. No extra semantic depth beyond the schema's own 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: creating a full cross-source profile of a US public company. It uses specific verbs like 'profile', 'research', and 'brief' coupled with the resource type, and explicitly distinguishes itself from single-pack lookups by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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

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

The description provides explicit usage context: it tells the agent to prefer this tool over chaining single-pack lookups for holistic views. It also states a clear exclusion (names not supported) and directs to resolve_entity as an alternative when only a name is available, offering actionable 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 destructiveHint=true and idempotentHint=true. The description adds context about the deletion being for previously stored memory and mentions clearing sensitive data, which is useful. 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, front-loaded with the core action, and every sentence provides useful guidance. 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?

With one simple parameter, no output schema, and annotations covering destructive/idempotent behavior, the description fully explains purpose, usage timing, and complementary tools. It is complete for the tool's simplicity.

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

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

Schema description coverage is 100%, with the property 'key' described as 'Memory key to delete'. The description's 'by key' phrase adds minimal new meaning, so baseline 3 is appropriate.

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

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

Description uses specific verb 'Delete' and identifies the resource as 'previously stored memory by key', distinguishing it from siblings like remember and recall. It clearly states the operation and scope.

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

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

Explicit when-to-use contexts are provided ('context is stale, the task is done, or you want to clear sensitive data'). The mention of pairing with remember and recall gives complementary tools, but no explicit when-not-to-use or alternative tool for the same task.

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 adds valuable context: it fetches the page, extracts specific elements, and returns a 'single text blob' in markdown format. This explains the network operation and output shape without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, followed by the mechanism and use cases. Every sentence adds value and there is 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?

Given the simple tool (2 params, no output schema), the description is complete: it covers the purpose, the process, the output format, and the practical use cases. The explanation that the output is 'a single text blob ready to drop at site-root/llms.txt' communicates the return value sufficiently.

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% (both url and max_links are described in the schema). The description adds no extra parameter details beyond mentioning the output, but the schema already fully documents both parameters, so no compensation needed.

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

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

The description uses a specific verb 'Generate' with a clear resource ('production-ready llms.txt file for any URL'), and explains the exact process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This fully distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing rather than generating the file.

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

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

The 'Useful for:' section gives three concrete use cases (client indexing, own project, competitor audit), providing clear context on when to use the tool. It doesn't explicitly mention when not to use or alternative tools, but the use cases are sufficient to guide 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the output fields but does not disclose additional behavioral context like error handling, URL validity requirements, or rate limits. 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 a single, scannable sentence that front-loads the primary purpose and enumerates the return values in a clear, concise manner. Every word earns its place, with no redundancy or filler.

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

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

For a one-parameter, read-only tool, the description conveys both the input (the layer URL) and the output (schema components) effectively. Given the rich annotations and simple schema, this is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage for the single 'url' parameter, and the description's 'by url' merely restates the schema property. The description does not add extra meaning such as URL format examples or constraints beyond what the schema already 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 states the tool retrieves an ArcGIS layer's schema by URL, listing specific output components like fields, geometry type, record count, and capabilities. It is specific about the resource and verb, but does not explicitly differentiate it from sibling tools such as query_layer, which may also deal with layers.

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?

No guidance is provided on when to use this tool vs. alternatives like query_layer or search_within. The description mentions 'by url' but does not state prerequisites, exclusions, or any conditions that would make this tool preferable over others.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat these. It adds valuable context by specifying that it returns only 'active' subscriptions by default and lists the return fields (id, type, params, etc.). This goes beyond annotations and helps the agent understand what to expect. 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 compact, with three sentences that each serve a purpose: state the action, list return fields, and give usage guidance. It is front-loaded with the main verb and resource, and contains no redundant or filler content.

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

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

For a low-complexity tool with one optional parameter and no output schema, the description is complete. It clearly states what the tool does, what data it returns, and when to use it. The listing of return fields compensates for the absence of an output schema, making the description sufficient for an agent to use correctly.

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

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

The schema includes a fully described optional parameter (include_inactive) with 100% coverage. The description adds minimal extra meaning about parameters, only implying the default behavior through the word 'active.' Per the rubric, baseline is 3 when schema description coverage is high, and the description doesn't significantly augment parameter understanding.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' This specifies a distinct verb ('List') and resource ('subscriptions') while distinguishing it from sibling tools like subscribe and unsubscribe. The additional detail about return fields reinforces the tool's specific role.

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

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

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent precisely when to invoke this tool relative to related actions like subscribing or unsubscribing. However, it doesn't explicitly state when not to use it or mention alternative tools, so it falls short of full explicit guidance.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limiting ('5 per identifier per day'), quota behavior ('free; doesn't count against your tool-call quota'), and impact ('team reads digests daily and signal directly affects roadmap'). These are behavioral traits beyond schema and 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?

While lengthy, every sentence earns its place: purpose, use cases, scope exclusions, message guidelines, and expectations. Information is front-loaded and logically ordered, with 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?

This is a simple feedback tool with no output schema and neutral annotations. The description covers all necessary context: what it does, when to use it, exclusions, message format, and behavioral constraints. It is fully sufficient for an agent to decide and 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 description coverage is 100%, so the baseline is 3. The description goes beyond by adding guidance on message content ('Describe the issue in terms of Pipeworx tools/packs') and connects type categories to use cases (bug, feature, data_gap, praise), enriching parameter semantics.

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

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

The description uses a specific verb ('Tell the Pipeworx team') and resource ('Pipeworx team') with a clear scope: reporting broken/missing/existing things. It also differentiates from sibling tools by being the only feedback-submission tool among research/query tools.

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

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

Explicit when-to-use guidance is given for each category (bug, feature/data_gap, praise), and it explicitly tells when NOT to use it (other MCP servers). It also provides a fallback ('Not sure? Pipeworx tool names are the ones this connection lists') and content guidance (don't paste end-user prompt).

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/no destructive. Description adds non-PII guarantee, CF analytics-engine derivation, and cache freshness (5min-1h depending on window). This is meaningful behavioral context beyond 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?

Front-loaded with main functionality, then use cases, then data/cache notes. Slightly longer than necessary but every sentence earns its place; organized with numbered use cases.

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?

Simple tool with one optional param and no output schema. Description explains return values (pack, tool, count), use cases, and caching. Adequate for agent to invoke correctly, though doesn't describe exact JSON structure, but not required.

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 provides 100% coverage for 'window' with enum and explanation of shorter vs longer windows. Description repeats windows but doesn't add new syntax or format details, so baseline 3.

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

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

Specific verb 'Returns' plus resource 'top tools, top packs, total call volume' over a time window. Distinguishes from siblings like discover_tools by focusing on what other AI agents are calling.

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 three use cases: discovering hot data sources, confirming canonical tool choice, and aligning with agent needs. Does not name alternatives or when-not-to-use, but gives 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behavioral nuances: the placeholder filter, the fill check against live CLOB depth, the condition where realizable_edge_pp ≤ 0 means 'do not trade it', and the semantic anchor with Jaccard similarity. These are substantive behavioral details not captured by annotations.

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

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

The description is extensive and dense, but the complexity of the tool justifies the length. It is well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check) and front-loaded with the core purpose. Some redundancy exists (e.g., repeating partition_check details), but every sentence adds operational value.

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

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

Given that there is no output schema, the description thoroughly covers return values (opportunities[], partition_check, fill_check details). It also addresses edge cases (placeholder slugs, low similarity) and provides risk warnings (realizable_edge_pp ≤ 0). It is remarkably complete for a complex, multi-mode 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 schema coverage is 100%, the description adds depth by explaining the operational semantics of each parameter: `event` walks child markets and checks ordering, `topic` searches across the platform and flattens markets, and omitting both triggers a trending_scan. It also provides concrete slug examples and explains how the parameters influence the response structure.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, which is a specific verb, resource, and method. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its unique detection mechanisms and two modes (event vs topic).

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

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

It provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also directs users to `polymarket_fill_risk` for custom sizing, clearly delineating when this tool vs an alternative 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?

With annotations declaring readOnly/openWorld/idempotent and non-destructive, the description adds substantial behavioral context beyond those flags: it discloses the internal model logic (lognormal barrier, GDELT article-volume ratio), the slippage assumptions, the '24h-move warning' that signals a stale edge, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). It also explains why partition overrounds return zero parent-level Kelly — all useful for interpreting the tool's outputs and side effects.

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

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

The description is front-loaded with the main purpose, but it is extremely long (roughly 500 words) and packs in a lot of implementation detail, such as per-sport α values (tennis 1.02, soccer 1.10, MMA 1.15) and exact funnel counters. While each sentence adds information, the sheer density makes it harder for an agent to quickly extract the key usage points. It would benefit from tighter organization or separating core behavior from optional deep-dive details.

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 complexity (9 params, no output schema), the description is exceptionally complete. It explains the response structure at top level ('by_segment{model_driven,...}', 'fed_candidates/fed_note', '_diagnostics{...}'), the edge metrics, the tradeable-edge knobs, and the logic behind exclusions. Callers understand exactly what they will receive and why certain segments might be empty (e.g., top-N stale, failed gates, knobs).

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 explaining how parameters interconnect, e.g., 'min_partition_leg_kelly... applies to the per-leg Kelly inside top_legs instead' and that 'min_kelly never filters them' for partition arbs. It also gives practical guidance like 'Bump for very thin partitions' for slippage_pp, making the knobs more actionable than the raw schema alone.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage by emphasizing the 'what should I bet on today' discovery use case and the unique model-family breakdown. This leaves no ambiguity about 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 explicitly frames the intended use case ('Built for what should I bet on today'), and explains when to use certain knobs (e.g., 'Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities'). It even notes exclusions like Fed bets ('excluded from ranking — 1m-T vs EFFR signal is unreliable'), but it does not explicitly name alternative sibling tools or state when not to use this tool, so it misses the 'when-not/alternatives' criterion 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?

The description goes far beyond the annotations, thoroughly disclosing response structure (tracked[], expired[], snapshot_dates[]), field meanings, computation details (trend and decay on |edge_pp_net|, negative sign indicates SELL YES), and limitations (60-day TTL, gaps when no scan occurred, daily closes not intraday). No contradiction with the readOnly/idempotent annotations.

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

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

The description is long but highly structured: purpose, arguments, response fields, and limits are clearly separated. Every sentence contributes meaningful detail—no filler or redundancy. It is front-loaded with the core purpose and then provides necessary technical specifics.

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

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

Since there is no output schema, the description fully takes on the burden of explaining return values, including the meaning of tracked vs expired, the trend enum, decay computation, and snapshot_dates. It also explains data gaps and TTL limits, making the tool's behavior fully understandable for an agent. This is complete for a complex telemetry tool.

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

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

Schema coverage is 100% and the schema already describes both parameters clearly (lookback in days, window family). The description repeats these defaults ('default 14, max 30', 'default 1wk') without adding significant new semantic meaning beyond what the schema provides. Any added nuance like 'snapshot family' is already present in 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 immediately states the tool's core function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from siblings like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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

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

The description provides a clear use case: evaluating whether an edge is fresh or aging, and explains the conceptual rationale ('the latter is wide for a reason nobody is willing to take'). It also sets expectations about limits (TTL, snapshot gaps). However, it does not explicitly name alternatives or state 'when not to use this tool', so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral detail beyond annotations: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), lists return fields like slippage_pp and max_fillable_usd, and warns about forced directional risk. There is no contradiction with annotations.

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

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

The description is dense but impeccably structured: opening purpose statement, REQUIRES constraint, SINGLE-MARKET and BASKET sections, return field lists, and final usage guidance. Every clause earns its place, with no fluff or redundancy, and the structure matches 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 the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It enumerates all return fields for both modes, explains parameter semantics, provides usage context, and warns about failure modes. It fully compensates for the missing output schema and leaves no ambiguity for an agent.

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

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

Input schema covers all 4 parameters at 100%, so baseline is 3. The description adds meaning beyond schema by clarifying size_usd as 'max spend on buys, target proceeds on sells' in single-market mode and as 'settlement notional — shares per leg' in basket mode. It also explains the auto-selection of side in basket mode based on partition sum, exceeding the schema's documentation.

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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates from siblings by focusing on fill risk/execution checks and explicitly references polymarket_arbitrage and polymarket_edges, making its purpose distinct and actionable.

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

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

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround not capturable, partial basket fills create unhedged directional risk) and provides mode selection guidance, exceeding basic usage hints.

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 and idempotentHint annotations, the description richly discloses behavior: it details the response structure (leg prices, spread, safety fields), explains the conditions for compatibility_warning, temporal_alignment, and skipped_cross_type counters, and warns that pre-mapped topics often are not tradeable. This is exemplary transparency for a complex analytical tool.

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-organized into clear segments (modes, response, safety fields, caveats). Every paragraph adds necessary operational context for a tool of this complexity, though it could be tightened slightly by trimming redundant emphasis on the rarity of tradeable spreads.

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 fully compensates by explaining the response fields, safety mechanisms, and the meaning of alignment and skip counters. It provides enough detail for an agent to call the tool correctly and interpret results across different scenarios.

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

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

The input schema already covers all three parameters with descriptions and examples, giving a high coverage baseline. The description adds significant semantic context (e.g., how topic maps to events, how explicit tickers override the mapped side, and the dual-mode behavior), which elevates the parameter understanding beyond the schema alone.

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

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

The description clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question, with a specific scope that distinguishes it from sibling Polymarket tools. It also outlines the two operation modes (topic shortcuts vs explicit tickers), making the purpose unambiguous.

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

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

The description provides clear usage context, explaining when to use topic shortcuts vs explicit tickers and how to interpret compatibility warnings. However, it does not explicitly name alternative tools or state when to prefer one over the other, so it stops short of full when/when-not guidance.

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

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

Annotations already declare it read-only and idempotent; the description adds behavior details like returning attribute rows and geometry, and the SQL-like query interface. No contradiction found, and the added context is meaningful beyond annotations.

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

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

The description is two concise sentences, front-loaded with the action and resource. It avoids repetition, and every clause adds practical information including a concrete usage example.

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, no output schema, and strong annotations/schema, the description covers core usage, return type, and important parameter behaviors. It lacks explicit pagination guidance and output format details, but remains sufficient for correct invocation.

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

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

Schema has 100% coverage of all 6 parameters, so the baseline is 3. The description reinforces SQL-like behavior and comma-separated out_fields, but adds limited new semantic value beyond the rich schema descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature Service / Map Service layer by URL, using a specific verb and resource. It also distinguishes itself from siblings like search_datasets and layer_info by focusing on data retrieval.

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

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

It explicitly indicates the URL should come from search_datasets and provides a practical sampling tip ('where="1=1" + out_fields="*"'). It does not explicitly state when not to use it or mention alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat these. It adds valuable context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID),' which explains isolation behavior. It also clarifies the 'list all' behavior when the key is omitted. This goes beyond annotations without contradicting them.

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

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

The description is three sentences, with the main action front-loaded in the first sentence. Every sentence adds meaningful information: the action, usage context, and scoping. There is no redundancy or fluff, and it is appropriately sized for a simple tool with a single optional parameter.

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 low-complexity tool with one optional parameter, rich annotations, and no output schema, the description covers all essential aspects: purpose, usage context, scoping, and relationship to sibling tools. It is complete enough for an agent to successfully select and invoke the tool without further clarification. The absence of return-format details is acceptable given the simplicity and the lack of an output schema.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter well ('Memory key to retrieve (omit to list all keys)'). The description adds semantic value by providing realistic examples of key contents (target ticker, address, research notes), which helps the agent understand what values might be stored. This elevates the score above the baseline of 3 for full schema coverage.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb+resource structure and distinguishes itself from siblings by referencing remember and forget. The inclusion of concrete examples (target ticker, address, research notes) further clarifies the intended use.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, giving clear guidance on the full workflow. This goes beyond simple context and names alternative/related tools, satisfying the criterion for explicit when-to-use guidance.

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

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

The description adds important behavioral details: the feed is persisted and written by the evaluator, each event includes a citation_uri (pipeworx:// when available), and setting mark_read:true flags events as read so subsequent calls return only newer items. This complements the annotations (readOnlyHint, idempotentHint) by disclosing the optional state-changing behavior clearly, without contradicting them.

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

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

The description is three sentences long, front-loaded with the core purpose, and each sentence earns its place by explaining behavior, parameters, and alternative integration. There is no redundancy or filler.

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

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

Given there is no output schema, the description conveys what the return payload includes (source, citation_uri, raw event). It covers filtering, mark_read semantics, and polling suitability. It also mentions the same feed is available via a URL for scripts/dashboards, which is a thoughtful contextual addition that covers alternative use cases.

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?

Even though the schema covers 100% of parameters, the description enriches their meaning: it gives a concrete example for 'type' (e.g. sec_8k), clarifies that 'since' is an ISO timestamp, and specifically explains the behavioral effect of 'mark_read' on future calls. This goes beyond the schema's basic 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', clearly identifying both the action (pull/list) and the resource (subscription feed alerts). It further specifies the content (source, citation_uri, raw event payload), making the tool's purpose distinct from sibling tools like recent_changes or list_subscriptions.

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

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

The description provides clear usage context: it is designed for polling ('Polls work fine'), shows how to filter by type and since, and explains the mark_read flag behavior. It also points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts, but does not explicitly contrast this tool 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses significant behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fails due to API sunset, and the parallel-call execution. It also describes the output grouping and citation URIs, providing rich context beyond the structured hints.

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

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

Despite its length, every sentence contributes a distinct fact: query examples, source list, fallback logic, parameter formats, return structure, and sibling comparison. There is no filler, and the content is front-loaded with the most salient usage 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?

For a tool with no output schema, the description sufficiently explains the return format (changes[] grouped by source, total_changes count, citation URIs). It covers edge cases (rate limits, API sunset), parameter details, and alternative tools, making it complete for an agent to select and invoke correctly.

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

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

The input schema already documents all three parameters with 100% coverage, including accepted formats and typical values. The description repeats these examples (e.g., ISO date vs relative shorthand, ticker vs CIK) but adds no new parameter-level semantics beyond what the schema provides. Therefore, a baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with concrete query examples ('What's new with X', 'updates on Acme'). It explicitly distinguishes itself from entity_profile by contrasting the dynamic feed with the static profile, so it is clearly differentiated from siblings.

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

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

The description provides explicit usage context: example natural-language triggers, the window formats, and the fallback behavior. It also gives an explicit alternative: 'Use entity_profile instead when you want the static profile', which tells the agent 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?

Annotations indicate idempotent, non-read-only, non-destructive behavior, and the description adds meaningful context: key-value storage scoped by identifier, 24-hour retention for anonymous sessions, and persistent memory for authenticated users. This goes well beyond the annotation hints without contradicting them.

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

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

The description is tightly written; every sentence contributes a distinct piece of information: purpose, when to use, storage semantics, retention policy, and relationship to sibling tools. It is front-loaded with the core action and remains under ~90 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 simple two-parameter write tool with no output schema, the description covers all relevant context: exact use cases, scoping/retention behavior, and pairing with recall/forget. Nothing important is missing for an agent to select and invoke it correctly.

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

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

The input schema already fully documents both required parameters (key and value) with 100% coverage, so the description adds no additional parameter syntax or format details. It reinforces that data is stored as a key-value pair, but this is largely redundant with the schema.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later' across conversation or sessions. It distinguishes itself from sibling tools by scoping the action to memory storage and explicitly pairing with recall/forget.

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 when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and clearly names complementary tools: 'Pair with recall to retrieve later, forget to delete.' It also notes session vs. authenticated persistence, helping the agent decide when memory is reliable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context beyond annotations: internal cascading through multiple endpoints, auto-disambiguation for company names, and the exact citation URIs returned. 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 appropriately detailed with a clear structure: use-case examples, supported types, and return values. Every sentence provides actionable information, and the format is front-loaded with the most important usage guidance.

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

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

Given no output schema, the description fully explains what is returned for each entity type (ticker, CIK, company_name, URIs for companies; RxCUI, ingredient, brand, URI for drugs). It also covers input variants and disambiguation, making the tool completely understandable.

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

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

Schema coverage is 100%, but the description enriches parameter understanding significantly. It explains that 'value' can be a ticker, CIK, or name for companies, and a brand or generic name for drugs, and mentions auto-disambiguation—details not in the schema.

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

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

The description uses specific verbs ('resolve', 'look up') and clearly states the tool maps user-spoken names to canonical identifiers required by other tools. It provides concrete examples ('ticker', 'CIK', 'RxCUI') and explicitly distinguishes itself from siblings by framing it as the 'FIRST' step when you have a name but need an ID.

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 directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies what input types are accepted and that using it replaces 2-3 manual lookups, making the decision to use this tool versus alternatives clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by revealing it 'Probes each entity ... with ai_visibility_check', 'ranks by score', and returns a ranked list with score/confidence/signal density. This goes beyond annotations by explaining the internal mechanism and output structure.

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

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

The description is three sentences, front-loaded with the primary purpose. It efficiently covers what, how, and why in a compact form with no filler or repetition of schema details.

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

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

Although there is no output schema, the description explains the return format (ranked list with score, confidence, signal density). Combined with a fully described input schema and annotations that clarify non-destructive, idempotent behavior, the description is sufficiently complete for a tool of this complexity.

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

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

Schema coverage is 100%: all four parameters have descriptions, including that entities' first entry is the subject. The description adds no new parameter-level meaning beyond what the schema already provides. Per the baseline rule for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states a specific purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses a strong verb (compare) and identifies the resource (AI visibility across entities). It distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, and mentions 'competitive AI-marketing audits' as a concrete use case.

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

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

The description gives a clear usage context (competitive AI-marketing audits) with an example query about whether Claude knows your brand vs competitors. It implies this is for multiple entities, contrasting with the single-entity sibling ai_visibility_check, but it does not explicitly say 'use this instead of X when comparing multiple entities' or provide exclusion criteria.

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

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

Beyond readOnly/openWorld/idempotent annotations, the description discloses partial failure behavior, timeout delays (5-30s), the sources_failed field, and the output structure. No contradictions.

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

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

Dense but each sentence provides distinct value: purpose, usage, return fields, ecosystem limitation, error behavior. Front-loaded with the core composite check 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?

The description adequately covers the tool's output structure, limitations, and failure modes, compensating for the lack of an output schema. Fully sufficient for an agent to decide and 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?

Both parameters are already fully described in the schema (100% coverage). The description adds little new parameter-specific detail, only general context about defaulting to latest version, which the schema already states. 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 states the tool's function as a composite npm package safety/size check, specifying the data sources (deps.dev, bundlephobia) and distinguishing it from other scan tools by ecosystem scope.

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

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

Explicit usage triggers are given ('is X safe / popular / small', 'what does adding lodash cost me'), plus explicit exclusion for non-NPM ecosystems that should use deps.dev directly.

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

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

The description discloses the return payload (name, summary, record_count, owner/org, url) and the downstream use of the url, adding value beyond the readOnly/idempotent annotations. It does not contradict the annotations.

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

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

Two concise sentences front-load the action and output summary with no fluff. The phrase 'pass that url to query_layer / layer_info' earns its place by connecting to companion tools.

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

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

Without an output schema, the description sufficiently details the returned fields and the integration point with query_layer/layer_info. The tool is lightweight and all critical information is present.

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

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

Schema coverage is 100%, with all three parameters described in the input schema. The description only echoes 'keyword', adding no extra parameter context beyond what the schema already provides.

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

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

The description clearly identifies the tool as a search over City of Cedar Park GIS open geospatial datasets by keyword, listing the exact metadata fields returned. It distinguishes itself from sibling tools by noting the Feature Service url can be passed 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 explicitly frames the tool as the discovery entry point and directs users to pass the resulting url to query_layer/layer_info. While it does not list exclusion criteria, the workflow linkage strongly implies when to use this tool versus the retrieval tools.

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

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

Annotations already mark readOnly and non-destructive; the description adds important behavioral context: returns character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and caps at 200K characters with truncation flagging. No contradictions.

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

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

The description is dense but well-organized, front-loading the core function, then use cases, then technical details. No filler—every sentence contributes.

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 explains the return values (top-N passages, character offsets, similarity scores) and covers limitations (truncation). It also gives grounding workflow context, making it self-sufficient.

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

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

Schema covers 100% of parameters with descriptions, but the description reinforces practical semantics: text must be pre-fetched, query is natural language, and limit caps at 20. It also notes the 200K char cap on text, adding 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 states a specific verb+resource: 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K body, article). It distinguishes itself from sibling tools by emphasizing it operates on already-fetched text and pairs with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This contrasts with alternatives effectively.

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?

Exceeds what annotations provide. It details authentication prerequisites, SMS verification and daily cap, webhook HMAC signing, auto-disable after consecutive failures, and the always-on feed. This gives a thorough understanding of side effects and operational behavior beyond the basic readOnlyHint/idempotentHint flags.

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

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

The description is longer than necessary and repeats examples already present in the schema (e.g., sec_8k items, polymarket_edge topic, fred_series series_id). While it is front-loaded with the core purpose, the latter portions are verbose and could be streamlined by referencing the schema for type-specific details.

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 prerequisites, delivery channel behaviors, and returns the subscription ID, which is sufficient for a create operation. It elaborates on three of the five types in depth, but the schema covers the remaining two, so completeness is strong. The lack of an output schema is mitigated by the explicit statement of the return value.

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

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

While the schema already covers 100% of parameters with rich descriptions, the tool description adds semantic context such as what 8-K filings represent, the meaning of polymarket_edge (cross-venue mispricings), and clarifies the SMS delivery constraint (verified phone, cap). This adds value beyond the schema's structural descriptions, though there is some overlap.

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

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

The description clearly states the tool's purpose with a specific verb ('Create'), resource ('proactive monitoring subscription to a live-data event stream'), and return value ('Returns the new subscription id'). It also lists supported types, fully distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description gives clear context for use, including the requirement for a Pipeworx OAuth account and the exclusion of anonymous/BYO users. It also mentions an alternative for pulling feed alerts via recent_alerts or a direct URL, providing some usage direction. However, it does not explicitly name alternative tools for other scenarios, so it lacks 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?

Annotations already cover readOnly/idempotent/openWorld. The description adds valuable context beyond annotations: results are 'drawn from the live catalog of thousands of tools' and include 'the exact tool + argument shape that answers it,' which clarifies what the agent can expect from a call.

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 and front-loaded with natural-language examples. Each clause delivers distinct information: what it returns, how to call it, and when to use it. It is efficient for an onboarding tool, though slightly dense.

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

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

The description is complete for a tool of this complexity. It explains the return payload (categories, examples, tool+argument shape), the optional and no-argument invocation modes, and its role in learning meta-tools. No output schema is needed given this thorough 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 coverage is 100% for the single optional `topic` parameter. The description enriches schema semantics by explaining that omitting it returns 'a cross-category spread' and passing it 'focuses' the results, with concrete examples like 'finance', 'pharma', and 'betting'.

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

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

The description clearly states the tool's purpose: it is the 'onboarding entry point' that 'returns category-bucketed example questions' with the exact tool and argument shape. It uses a specific verb and resource, and distinguishes itself from siblings by positioning as the first tool to use when unfamiliar with 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?

Explicitly instructs to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with no arguments versus passing a topic to focus. It does not name specific alternative sibling tools, but the 'FIRST' guidance provides clear usage 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 meaningful behavioral details beyond annotations: ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This complements the idempotentHint and destructiveHint 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?

Two sentences deliver the core action, the ownership constraint, and the deactivation behavior with no filler. The information is front-loaded and every clause adds value.

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

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

For a one-parameter tool with no output schema and high annotation coverage, the description fully clarifies what the tool does, who can use it, and its side effects. It also connects to the recent_alerts sibling for historical context.

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

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

Schema coverage for the only parameter is 100%, with the schema already explaining that id is a subscription uuid returned by subscribe. The description adds little beyond restating 'by id', so the schema carries the semantic load.

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

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

The description opens with 'Cancel a subscription by id,' clearly stating the action (cancel), the resource (subscription), and the scope (by id). This distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

The description implies usage for canceling existing subscriptions and notes the ownership constraint, which guides correct invocation. However, it does not explicitly mention when to prefer this over alternatives such as subscribe or recent_alerts.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses significant behavior: the two routing paths, return of verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), inclusion of pipeworx:// citations and reasoning, and the toll of replacing 4–6 sequential calls. This adds substantial context that annotations alone don't provide.

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

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

The description is long but every sentence carries information: trigger phrases are front-loaded, the two routing paths are clearly separated, and the return value is summarized. It's dense but efficiently structured, though it could be slightly trimmed without losing value.

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

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

Given there's no output schema, the description adequately explains what the tool returns (verdicts, actual value with citation, reasoning). It also covers edge cases (any other factual claim) and performance benefits. Annotations cover safety, so the description focuses on behavior and results, making it 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?

While schema coverage is 100%, the description adds crucial meaning to tolerance_pct—explaining the acceptable range (0.5–50), the override behavior relative to claim wording, and the practical use for hallucination detection (set 1–2). The claim parameter is also illustrated with concrete examples, enriching the schema's basic description.

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

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

The description opens with trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It explicitly states the tool checks whether something a user said is factually correct, and the scope (financial vs. other claims) is precisely defined, distinguishing it from sibling tools like ask_pipeworx or compare_entities.

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

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

Provides strong when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the branching within the tool (SEC EDGAR for company financials, grounded pipeline for other claims). However, it doesn't explicitly name sibling tools as alternatives or state exclusions, so it's clear but not exhaustively comparative.

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