Arcgis Branson

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable transparency by explaining the free default model (Workers AI), the cost implications of passing an Anthropic key ('BYO key — you pay Anthropic directly'), and the exact response structure. 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 three sentences, purpose-first, with every sentence providing necessary information: what it does, the default behavior and API key implication, and the return payload. No filler or redundant phrasing.

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

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

Despite lacking an output schema, the description fully conveys behavior, defaults, optional API key usage, return shape (per-model score/confidence/signals/raw_response plus combined view), and common use cases. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter has a meaningful description. The description supplements this by highlighting the free default model and that using Anthropic incurs direct cost, which adds practical meaning to the 'models' and '_apiKey' parameters beyond the schema's technical details.

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: 'Probe one or more LLMs for what they know...' and clearly states the output (visibility score 0-100 per model). This distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence by focusing on cross-LLM knowledge scoring rather than Q&A or a single platform.

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 use-case context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or exclusions, but the use cases imply when this tool is appropriate. A 4 is warranted for clear context without explicit alternative guidance.

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

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

Beyond the strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses internal routing behavior, the citation URI scheme, 'one fast call' performance, and cross-tier availability. It adds substantial behavioral context without contradicting any annotation.

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

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

The description is long but every sentence serves a purpose: it front-loads the preference directive, lists domains, explains the tool's mechanism, provides examples, and clearly delineates alternatives. It is well-structured and free of redundancy.

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

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

Given the tool's high complexity (a meta-router over thousands of sources) and lack of an output schema, the description fully explains return behavior (structured answer with pipeworx:// citations), usage context, alternatives, and example inputs. It leaves no important gap for an agent to misinterpret.

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

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

The schema already documents the 'question' parameter and all five aliases with descriptions, achieving 100% coverage. The description provides useful examples and emphasizes natural language input but does not add meaningful parameter-level semantics beyond the schema's baseline.

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

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

The description clearly states the tool's purpose: it routes questions to one of 5,529 tools across 1,455 sources, fills arguments, and returns structured answers with stable citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Extensive guidance is provided: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions' establish default use, while explicit conditions list trigger phrases like 'what is', 'look up', and 'current'. It also names specific alternatives with criteria for escalation (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions).

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 that routing improvements are enabled live only when under test, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. Also states it is a full working router with no fallback, adding context beyond 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 a single, slightly dense sentence that packs in beta status, current state, usage instruction, and nature. It is front-loaded with the most important identifier and remains informative, though it 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?

Despite no output schema, the description states the response shape is identical to ask_pipeworx, covering return expectations. It also communicates the experimental context and current equivalence, making it sufficient for an agent to select and invoke appropriately.

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

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

The schema already provides 100% coverage with descriptions for all six parameters, including aliases. The tool description adds no additional parameter-specific information beyond confirming they are the same arguments, so it does not enhance 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 this as a beta version of ask_pipeworx, a universal router for natural language questions, and distinguishes it from the stable version by its experimental routing improvements. It names the specific sibling tool (ask_pipeworx) and explains the identical behavior, 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?

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and implies the stable alternative for non-experimental use. Mentions results are compared against the stable router, providing clear usage context and alternative differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial context: the refusal_reason enum (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the evidence/verbatim quote, and the additional LLM call cost. It fully discloses how the tool behaves on failure and success, far exceeding the annotation baseline.

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

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

The description is dense yet efficient—about 4 sentences—and front-loaded with the core purpose. Every sentence adds unique value (cost, refusal reasons, when-to-use, return format). It avoids fluff and is appropriately sized for a tool with this complexity.

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

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

With no output schema, the description fully explains the return structure: {answer, evidence, confidence, source, fetched_at, refusal_reason:null} on success and the refusal variant on failure. It also covers the extra LLM call cost and the use cases, making it complete 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%, with each of the 6 parameters described as aliases for 'question'. The description itself adds no extra parameter semantics beyond what the schema already provides. Per the rubric, baseline 3 is appropriate when schema covers parameters fully and description does not need to compensate.

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.' It specifies the exact behavior (picks the right tool, fetches data, extracts the answer using ONLY what the tool result contains) and differentiates itself from sibling ask_pipeworx by the refusal mechanism and evidence extraction. This goes beyond a simple verb+resource and clearly distinguishes from alternatives.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This tells the agent exactly when to choose this tool over its sibling, including exclusions for casual use. The added cost of 'one extra LLM call' further informs the decision.

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

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

The description adds substantial behavioral context beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It discloses fan-out behavior, GDELT fallback mechanisms, resolution confidence handling, closed-market short-circuiting, wide-spread tradeability flags, and cancellation-rule parsing. It also explains the 'low_confidence_match' and 'market_closed_or_inactive' statuses and how they block further analysis. No contradiction with annotations.

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

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

The description is long and dense, but every sentence adds unique value for a complex tool. It is well-structured with clear section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), and the first sentence front-loads the primary purpose. It could be slightly trimmed, but given the number of behaviors and return-field explanations, the length is justified.

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

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

Given the high complexity, no output schema, and rich annotations, the description provides an exceptionally complete picture. It explains response shapes, the resolver contract, parent_event extraction, news fallback fields, safety mechanisms, and cancellation-rule risk. An agent would know exactly what to expect from the tool and how to interpret edge cases, making it fully self-sufficient for correct invocation and use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the market parameter's accepted formats (slug, URL, question text) but does not add new syntax details beyond the schema. It does provide examples of fan-out behavior that indirectly clarify depth, but it doesn't explicitly connect depth to those examples. The include_raw parameter is not mentioned in the description, though the schema covers it. Overall, the description doesn't significantly enhance parameter understanding beyond what the schema already provides.

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

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

The description clearly states the tool's core function: researches a Polymarket bet by pulling relevant Pipeworx data in one call. It specifies the resource (a Polymarket bet), the action (research/pull data), and the method (resolves, classifies, fans out). It also distinguishes from siblings by focusing on a specific bet's evidence packet and market-vs-model comparison, unlike broader tools like deep_research or polymarket_edges.

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

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

The description explicitly tells when to use it: for questions like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides abundant examples of fan-out scenarios. However, it does not explicitly mention alternatives or when not to use it, though the use cases are sufficiently clear. Safety warnings about low-confidence matches and closed markets provide cautionary 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?

Although annotations already declare this as a safe read operation (readOnlyHint, idempotentHint), the description adds rich behavioral detail: it pulls specific financial data points from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This goes far beyond the annotations and helps the agent anticipate output and edge cases.

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

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

The description is front-loaded with common trigger phrases and gets to the core purpose immediately. Every sentence adds substantive information: limits, data sources, fiscal-year handling, sorting, output format, and efficiency. Despite being lengthy, there is no fluff; each clause is necessary for correct tool use.

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 takes on the burden of explaining return values, which it does ('paired data + pipeworx:// citation URIs'). It covers edge cases (off-calendar fiscal years), sorting behavior, and the exact data pulled per entity type, making the tool fully self-contained and well contextualized.

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

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

The schema already fully describes both parameters with 100% coverage, so the baseline is 3. The description adds extra meaning by explaining how each 'type' value affects the data source (10-K metrics for company, FAERS counts for drug) and by giving concrete examples ('AAPL', 'ozempic'), which clarifies the intended format and behavior beyond the bare 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 states a specific verb ('compare') and a specific resource ('2–5 companies or drugs'), and clearly delineates what the tool does: a side-by-side comparison in one parallel call. It also distinguishes itself from siblings by explicitly contrasting with 'sequential single-pack lookups' and mentioning the ability to rank or compare, which is unique among the sibling tools.

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

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

The description gives explicit trigger examples ('X vs Y', 'which is bigger') and a strong directive ('ALWAYS PREFER over sequential single-pack lookups'), telling the agent when to use this tool instead of alternatives. It also implies usage boundaries by limiting to 2–5 entities and clarifying data sources per type, giving clear context without needing to mention exclusions explicitly.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds extensive context: account and paid-plan requirements, output structure (gaps[], contradictions[], hop field), citation resolvability, semantic excerpting (not head-truncated), and latency ('Expect 15-60s; thorough ... up to ~90s'). No contradiction with annotations; it complements them richly.

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

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

The description is long but information-dense, with the critical account requirement front-loaded and every clause carrying meaningful caveat. It is a single wall of text; while not wasteful, bullet points or clearer paragraph breaks would improve skimmability. Still earns a 4 because it remains purposeful and well-prioritized.

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 this complexity, the description is exceptionally complete: prerequisites (sign in, paid plan), alternatives, output format, error/gap handling, contradictions, citation policy, latency, and depth semantics are all addressed. There is no output schema, so this prose carries the entire load, and it succeeds.

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 goes beyond field-level docs: it explains depth in terms of hop behavior (standard 're-angles unanswered facets', thorough 'chases leads + recovers gaps'), and clarifies that the question parameter accepts broad/multi-part questions because decomposition is the point. This adds semantic 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 opens with a specific verb + resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call.' It clearly distinguishes this tool from open-web search and from ask_pipeworx, stating exactly what it does and how it differs 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?

Explicit guidance appears in the middle: 'Best for broad/multi-part questions over structured data.' It then gives alternatives: 'For a single lookup use ask_pipeworx' and warns that current-news topics should use ask_pipeworx because deep_research 'returns mostly empty gaps[]'. This is textbook when-to-use/when-not-to-use guidance.

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

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

Annotations already mark this as read-only and idempotent, so the description doesn't need to cover safety. It adds valuable behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas' and notes results are 'ready to call directly, no second schema lookup needed.' This tells the agent what to expect and how to use the output.

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

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

The description is two sentences with a front-loaded main clause. The domain list is somewhat long but informative, and the second sentence explains both return format and usage context without unnecessary verbosity.

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

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

The tool is a simple discovery endpoint, and the description covers its purpose, return format, and recommended usage. While there is no output schema, the description compensates by specifying that results include names, descriptions, and schemas. This is sufficient for an agent to invoke the tool and interpret its response.

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

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

The input schema already provides thorough descriptions for 'query' and aliases, achieving 100% coverage. The description does not add significant semantic detail beyond what the schema conveys, though it reinforces that the query is a natural language description of the task.

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' and lists the domains it covers. It distinguishes itself from sibling data tools by positioning itself as a discovery/meta tool to 'see the option set' before calling specific tools.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. It lacks an explicit 'when not to use' but the guidance is clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial behavior context: it fans out across multiple sources in parallel, returns specific data fields, soft-fails for the USPTO PatentsView API after May 2025, and uses a GDELT-to-GNews fallback. It also discloses the limitation that only ticker/CIK values are accepted. No contradiction with annotations.

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

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

The description is long but front-loaded with example queries and a clear directive ('full cross-source profile'). It includes a structured list of return fields, which is dense but useful. Slightly verbose for a description, yet every sentence adds value, so it earns a 4 rather than a 5.

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

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

There is no output schema, so the description takes on full responsibility for explaining return values. It enumerates exactly what will be returned: cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, and LEI. It also covers limitations and fallback behavior, making it complete for a complex cross-source tool.

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

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

Schema description coverage is 100%, with both type and value fully documented. The description adds example values (AAPL, 0000320193) and repeats the name limitation, but does not meaningfully extend beyond the schema. Baseline of 3 is appropriate since the schema already carries the parameter semantics.

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

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

The description clearly states this tool produces a 'full cross-source profile of a US public company in ONE parallel call,' with a specific resource and scope. It also distinguishes itself from siblings by explicitly saying to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-only inputs.

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

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

The description gives explicit when-to-use guidance: use when the user asks for a holistic view or asks to 'tell me about X,' 'research Acme,' etc. It also provides a clear exclusion and alternative: names are not supported, so use resolve_entity first if only a name is available.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds contextual behavior beyond that by noting the tool is for clearing stale or sensitive data and mentions its role alongside remember/recall, which is helpful for understanding the intended effect.

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

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

Two sentences, front-loaded with the action, and every phrase earns its place. It efficiently covers purpose, usage triggers, and sibling pairing with no wasted words.

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

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

The tool has a single required parameter, no output schema, and strong annotations. The description fully covers why and when to use it, what it does, and how it fits with related tools, making it complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% and the only parameter 'key' is described as 'Memory key to delete'. The description adds no further semantic detail about the key (e.g., format, required shape), so it does not go beyond the schema's documentation. Baseline 3 applies.

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

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

The description opens with a clear verb+resource: 'Delete a previously stored memory by key.' It also distinguishes from siblings by explicitly mentioning 'previously stored memory' and pairing with 'remember and recall', which are clearly separate functions.

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

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

It explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also provides integration guidance via 'Pair with remember and recall', effectively steering the agent away from alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds process details beyond annotations: it fetches the page, extracts specific elements, and emits a standard format. It also clarifies the output is a single text blob ready for site-root, which is useful behavioral context not captured in structured metadata.

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

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

The description is three sentences long, front-loads the primary purpose, and packs in essential details (input, process, output format, use cases) without redundancy. Every sentence earns its place, making it highly efficient.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description adequately covers the return format ('standard llms.txt markdown format', 'single text blob'). Annotations cover safety and idempotency, and the schema explains parameters, so the description is complete for an agent to select and invoke the tool correctly.

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

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

The schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description itself adds no additional parameter-level detail beyond what the schema already provides (e.g., url and max_links are fully documented 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 opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly explains the process (fetches page, extracts title/description/key links, emits standard markdown) and the output, making the tool's purpose unambiguous and distinct from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 explicitly lists three scenarios: indexing a client's site, drafting llms.txt for your own project, and auditing a competitor. This provides clear context for when to use the tool, though it doesn't explicitly mention alternatives or situations when not to use it, stopping short of a full 5.

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

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

The description adds specific output details (fields with name+type, geometry type, record count, capabilities) beyond the annotations, which already declare read-only and idempotent behavior. It does not mention error handling or rate limits, but given the strong annotation coverage, this is still solid.

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

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

The description is a single, well-structured sentence with upfront verb placement and no redundant words. It packs the return contents into a compact list, earning a perfect score.

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

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

For a simple read-only tool with one parameter and no output schema, the description adequately covers the return values and the target service type. It lacks caveats about invalid URLs or Map Server variants, but these are minor gaps given the simplicity.

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

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

The input schema already documents the 'url' parameter with a clear description and example (100% coverage). The tool description merely repeats 'by url' without adding new semantic detail, so it sits at the baseline.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('an ArcGIS Feature/Map Service layer's schema') with a detailed list of what it returns (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like query_layer, which would retrieve data rather than schema.

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

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

The description clearly states what the tool does but does not explicitly mention when to use it over alternatives or provide exclusions. While the purpose implies usage for schema retrieval, there is no direct comparison to siblings such as query_layer or search_within.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by enumerating returned fields (id, type, params, created_at, last_fired_at, fire_count), going 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?

Two sentences, front-loaded with purpose and return fields, followed by concise usage guidance. No redundant or filler content.

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

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

For a simple list tool with one optional parameter, the description covers purpose, output fields, and usage. Schema and annotations cover the remaining details, making it complete.

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

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

Schema coverage is 100% with a clear description for include_inactive. The tool description does not add additional parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing rather than mutation.

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

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

The description provides explicit usage context: 'review what you're monitoring before adding more or to find an id to cancel.' This implies when to use (before subscribing/unsubscribing) but does not explicitly name siblings as alternatives.

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

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

Despite the annotations being minimal, the description discloses important behavior: rate-limiting (5 per identifier per day), no tool-call quota impact, the claim_token flow for later retrieval, and daily digest review. This substantially exceeds what the annotations provide and prevents misuse.

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

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

The description is dense but every sentence serves a purpose: purpose, usage boundaries, token handoff, rate limits, and roadmap impact. It is front-loaded with the core action and uses clear, scannable sentences. No filler or redundancy.

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

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

With no output schema, the description still explains the key return artifact (claim_token) and the workflow for following up. Combined with the fully described schema and rich usage guidelines, an agent has everything needed to invoke the tool correctly in all intended 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?

Schema description coverage is 100% and the schema already explains each parameter well. The description adds value by giving a concrete usage example for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and emphasizing that it should be used with no other arguments, which is not fully clear from 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 opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly frames the tool as a feedback channel for Pipeworx tools, which clearly differentiates it from sibling information-gathering or research tools like ask_pipeworx or deep_research.

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

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

Provides explicit when-to-use guidance for each feedback type ('bug', 'feature/data_gap', 'praise') and gives a strong exclusion: if the tool came from a different MCP server, file elsewhere. It even tells uncertain agents how to identify Pipeworx tools, making the decision boundary unambiguous.

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

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

Beyond the read-only and idempotent annotations, the description discloses important behavioral traits: it is a 'self-aggregating signal' derived from 'CF analytics-engine', it contains 'no PII', and it has a cache window ('Cached 5min-1h depending on window'). This adds meaningful context about data provenance, privacy, and freshness that annotations do not cover.

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 slightly longer than minimal, but every sentence adds value: purpose, outputs, use cases, data source/privacy, and caching. It is well-structured and front-loaded with the main verb and resource, making it easy to scan. It earns a 4 rather than 5 because the use-case list could be tightened without losing essential 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 a single optional parameter and no output schema, the description is complete: it explains what is returned (top tools, top packs, total call volume), the temporal windows, the aggregating behavior, privacy, and caching. It leaves no critical ambiguity for a safe, read-only tool.

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

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

The schema covers 100% of the parameter, including its default and the trade-off between shorter and longer windows. The tool description merely restates the window options ('24h, 7d, or 30d') without adding new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb ('Returns') and clearly identifies the resource: 'what other AI agents are calling on Pipeworx right now' plus the concrete outputs (top tools, top packs, total call volume). This distinguishes it from siblings like discover_tools by focusing on agent call volume and trend aggregation rather than tool discovery.

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

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

It provides three explicit use cases ('Useful for: (1) discovering... (2) confirming... (3) seeing whether...'), which gives clear context on when to invoke this tool. However, it does not name alternative tools or state when not to use it, so it stops short of full exclusionary 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?

Even though annotations already declare the tool read-only and non-destructive, the description adds substantial behavioral context: it discloses the >3pp deviation threshold, the ≥0.30 Jaccard similarity anchor, the partition placeholder filter with >20% cap, the response structure, and the fill-check logic warning that realizable_edge_pp ≤ 0 means the trade should not be executed. This is far beyond what annotations provide and gives the agent critical operational details.

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

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

While long, every sentence earns its place given the tool's complexity. The description is front-loaded with the overall purpose and mode selection, then logically structured with labeled sections like SEMANTIC ANCHOR, PARTITION FILTER, Response, and FILL CHECK. It is dense but not redundant; the technical details are necessary for correct tool invocation and interpretation.

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

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

Despite having no output schema, the description explains the primary response fields (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context, and partition_check details). It covers all three invocation modes, parameter semantics, filters, and the fill-check process. It also links to a related tool for sizing, making the description complete for the tool's complexity.

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

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

The schema has 100% coverage for the two parameters, but the description greatly enhances them. It provides concrete examples for `event` slugs like 'fed-decision-may-2026' and notes that full URLs are accepted. For `topic`, it gives seed question examples and explains the cross-event search behavior. The description also explains the mode-dependent behavior and response differences, adding meaning well beyond the schema's simple type and description fields.

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

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

The description opens with a clear verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It defines the exact scope (monotonicity violations and partition-sum checks) and distinguishes itself from sibling Polymarket tools by specifying the arbitrage methodology. The three modes (trending_scan, event, topic) are clearly outlined, leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use each mode: call with no args for a trending scan of top markets, pass `event` for a specific market, and pass `topic` for cross-event scanning. It even recommends `event` for a specific market and explains that cross-event mode catches patterns single-event misses. It also directs the agent to a sibling tool for related needs: 'For custom sizing use polymarket_fill_risk.' This provides clear when-to-use and alternative guidance.

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

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

The description goes far beyond the annotations by detailing caching (1h KV), segmentation logic, edge calculation methodology (lognormal barrier, GDELT ratio, overround, favorite-longshot bias), what each opportunity returns (edge_pp_net, kelly_fraction, etc.), and diagnostics for empty segments. There is no contradiction with the readOnlyHint or idempotentHint annotations.

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

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

The description is long but well-structured with clear section markers and front-loaded purpose. It is dense with valuable information, and while some sections overlap with the schema (e.g., TRADEABLE-EDGE KNOBS repeats parameter descriptions), every sentence adds meaningful detail about tool behavior, making it appropriately sized for 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 the tool's complexity (9 parameters, multiple response segments, diagnostics), the description is exceptionally complete. It explains the response top-level structure, what each model family does, how diagnostics help understand empty segments, and provides caveats like the Fed signal unreliability. Since there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly.

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%, providing a baseline of 3. The description adds extra meaning for several parameters, such as min_partition_leg_kelly explaining why parent-level Kelly is 0 and how it applies per-leg, and slippage_pp providing context about Polymarket fees and typical slippage. This goes beyond the schema's already thorough 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 purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the use case 'what should I bet on today' distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear context for when to use this tool: for discovering betting opportunities without manually paging markets. It also explains the knob adjustments and notes that Fed bets are excluded from ranking. However, it does not explicitly name alternative tools or list when-not-to-use scenarios, though the unique focus is implied by the sibling tool names.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. The description adds rich behavioral context: snapshot TTL (60-day), snapshot creation on cache-miss, decay computed from daily closes not intraday, and the meaning of negative edge values. 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 front-loaded with purpose, then organized into Args, RESPONSE, and LIMITS sections. Every sentence carries essential information, with no filler. Despite length, it is densely informative and well-structured.

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, but the description fully enumerates the response fields (tracked, expired, snapshot_dates) and explains their significance. It also discloses historical depth limits and data caveats. For a complex time-series telemetry tool, this is exceptionally complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates defaults ('default 14, max 30') and window families already in the schema. It adds minimal new semantic value beyond what the input schema provides, though the mention of 'snapshot family' gives slight context.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question ('how long has this edge existed and is it shrinking?') and differentiates from fresh vs. old edges, distinguishing it from sibling tools like polymarket_edges.

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

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

The description clearly implies when to use this tool: when you need historical edge persistence and decay context. It contrasts fresh vs. 3-week-old edges, providing decision-relevant usage context. However, it does not explicitly name alternatives or state 'use this instead of X', so it falls short of a full exclusionary guideline.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description goes beyond by detailing what the tool does internally: 'walks the ladder', returns verdicts and fill details, identifies thin legs, and warns about partial basket fills converting arbs into directional positions. No contradiction with annotations.

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

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

The description is long but every sentence carries information: purpose, mode details, outputs, and usage guidance. It is front-loaded and logically organized (single-market then basket). Slightly dense, but justified by the tool's multi-mode 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?

No output schema exists, so the description fully carries the burden of explaining return values. It lists all outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers edge cases (thin books, partial fills) and usage context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mirrors what the schema already states (defaults, clamp ranges, mode-specific meanings). It adds minor emphasis on 'single-market' vs 'basket' semantics, but does not introduce significant value beyond the structured fields.

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

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

The description opens with a specific verb+resource+scope: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and explicitly ties to sibling tools polymarket_arbitrage and polymarket_edges, disambiguating from other Polymarket-related 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why: theoretical overround on thin books is not capturable, and partial basket fills create unhedged directional risk, effectively naming when not to rely on theoretical edges.

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 note readOnly/openWorld/idempotent, and the description adds valuable behavioral context: price gap rationale, leg-by-leg price structure, compatibility_warning conditions, temporal_alignment semantics, and skip counters. 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 lengthy but well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is dense with non-redundant detail; a bit more trimming could improve focus, but it remains appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully explains return values (leg-by-leg prices, top_spreads_pp, compatibility_warning, skipped_cross_type, temporal_alignment) and their interpretation, including edge cases. This is sufficient for the agent to call the tool and interpret results.

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

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

Schema coverage is 100% but the description enriches semantics: topic is a pre-mapped shortcut with a fixed list, while kalshi_event_ticker and polymarket_event_slug override mapped sides and enable custom pairings. Examples further clarify usage.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from siblings by detailing two modes and safety fields, so an agent knows exactly what this tool does and how it differs from alternatives.

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 explains two usage modes (topic shortcuts vs explicit tickers) and when each is appropriate, plus when the tool returns non-tradeable results via compatibility_warning. It lacks direct mentions of sibling alternatives, but the context is clear enough for selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral details beyond that: it returns attribute rows (and geometry), uses SQL-like syntax, and suggests a sampling trick. It does not cover pagination details, but that is partially in the schema.

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

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

The description is compact: one sentence listing capabilities and a brief usage tip. It is front-loaded with the main action and resource, contains zero filler, 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?

Given 6 parameters, full schema documentation, and strong annotations, the description covers the essential context: source, return type, and a practical example. It could optionally mention using layer_info to discover field names, but this is not critical, making 4 a fair score.

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 each parameter described. The description adds a sampling tip and clarifies the SQL-like nature, but it does not introduce new parameter-level semantics beyond what the schema already offers, 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 uses a specific verb ('Query') and identifies the exact resource ('ArcGIS Feature Service / Map Service layer'), including the source ('from search_datasets'). It clearly distinguishes this from sibling tools like layer_info (metadata) and search_within, 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?

It provides helpful context by linking to search_datasets and gives a concrete sampling pattern ('where="1=1" + out_fields="*"'). However, it does not explicitly state when to avoid this tool or name alternatives, so it misses 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 readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations by explaining the scoping mechanism ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key to list all entries. This goes beyond what annotations provide, though it does not detail return formats or edge cases like missing keys.

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

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

The description is remarkably concise: three sentences with zero wasted words. The first sentence states the core action, the second explains the intended use case, and the third adds scoping and relationship to sibling tools. Every sentence earns its place.

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

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

This is a simple tool with a single optional parameter, strong annotations, and no output schema. The description fully covers what it does, when to use it, and key behavioral context (scoping, listing mode). No critical information is missing; the tool is adequately specified for an agent to use it correctly.

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

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

Schema description coverage is 100% (the key parameter is fully described: 'Memory key to retrieve (omit to list all keys)'). The description essentially repeats the schema's meaning ('omit the key argument' to list all keys) without adding new syntactic or format details. Per the rubric, baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs (retrieve/list) and a specific resource (saved keys/values), and explicitly contrasts with sibling tools remember and forget, which distinguishes it effectively.

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 to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explicitly directs pairing with remember and forget, giving clear guidance on when to use this tool versus related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which the description does not contradict. It adds valuable context beyond annotations: the optional mark_read:true mutates read state, affecting subsequent calls, and notes the feed is persisted across calls. The potential nuance of mark_read conflicting with readOnlyHint is surfaced clearly, so the agent is fully informed.

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

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

The description is concise and front-loaded, starting with the essential action. Each sentence adds value: the returned payload, filtering options, mark_read side effect, and external access. No word is wasted, and the structure moves from core function to 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?

Given the lack of an output schema, the description sufficiently explains return values (source, citation_uri, raw event payload). It covers key usage aspects (filtering, polling, read-tracking, external endpoint) and is complete for a read-only alert retrieval tool with five optional parameters.

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 meaning beyond the schema: it gives an example for type ("sec_8k"), clarifies since as an ISO timestamp, and explains the behavioral effect of mark_read:true. This enriches the parameter definitions, though limit and unread_only are not further elaborated beyond their 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 opens with 'Pull fired events from your subscription feed,' a specific verb+resource+scope that clearly identifies the tool's function. It distinguishes itself from siblings like recent_changes by focusing on alerts from a subscription feed and describing the returned data (source, citation_uri, raw payload).

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

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

The description provides clear context for use: polling is safe, filtering by type and since, and setting mark_read. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, but does not explicitly compare to sibling tools or state when not to use it, leaving a small gap.

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

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

Discloses fan-out to multiple APIs, GDELT→GNews fallback behavior, USPTO PatentsView sunset with soft-fail, and return structure—much beyond the readOnly/idempotent annotations, and it does not contradict 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 fairly long but tightly packed with essential details; every clause contributes (queries, sources, fallbacks, return values). Slightly dense but not wasteful.

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

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

Despite no output schema, the description explains the return shape (changes[], total_changes, citation URIs), source specifics, fallback behavior, and even points to an alternative tool—comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters. The free-text description reinforces `since` formats and usage but adds little new meaning beyond the schema.

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

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

The description clearly states the tool provides a 'change feed for a company' with sources (SEC, news, patents) and explicitly contrasts with entity_profile, making it easy to distinguish 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?

Provides explicit natural-language query examples and an explicit when-not: 'Use entity_profile instead when you want the static profile.' This is clear usage guidance.

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

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

The description discloses key behavioral traits beyond annotations: memory is scoped by identifier, persistent for authenticated users, and retained only 24 hours for anonymous sessions. It does not contradict annotations (readOnly=false, idempotent=true) and adds meaningful context about data lifecycle.

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

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

The description is four sentences, each earning its place: function, use case, scoping/persistence, and pairing with siblings. It is concise without fluff and front-loads the core purpose.

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

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

For a simple key-value write tool with no output schema and high parameter coverage, the description is complete. It covers usage, persistence, scoping, and alternatives, leaving no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100% and each parameter already has a description, so baseline is 3. The description adds extra semantics by giving examples of key formats ('subject_property', 'target_ticker') and clarifying that value is 'any text,' which enriches the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It uses a specific verb (save) and resource (data/memory), and distinguishes it from siblings by pairing with 'recall' and 'forget' for retrieval and deletion.

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 provided: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives: 'Pair with recall to retrieve later, forget to delete,' which clarifies 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 already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral details: cascading through multiple endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers, and source attribution for each identifier. This exceeds 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 well-structured, starting with example usage patterns and then detailing supported types. Every sentence adds value, though it could be more concise. It is front-loaded with the most critical guidance ('Use FIRST whenever you have a name but need an ID').

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, the description is comprehensive. It covers input patterns, output behavior (including unresolved identifiers and source labels), graceful degradation, and the multi-endpoint cascade. No output schema exists, so the description appropriately carries the burden of explaining return values.

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 adds further meaning by explaining valid input formats for 'value' (e.g., ticker, CIK, name, drug brand/generic) and enriches the enum meanings for 'type' with detailed output expectations. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to canonical identifiers required by other tools. It provides concrete query examples and explicitly distinguishes its role from other tools by stating 'Use FIRST whenever 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 explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also indicates that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention alternatives or when not to use it, though the context is clear enough.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This adds return-format and mechanism context beyond the annotations, with no contradiction.

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

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

The description is three sentences: purpose, mechanism, and example use case. Every sentence adds value, and the structure front-loads the main purpose before 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 absence of an output schema, the description adequately covers return values (ranked list with score, confidence, signal density) and the operational context (which probe tool is used, first entity as subject). It doesn't cover edge cases like probe failures or minimum entity count, but the schema covers constraints. Overall, it's sufficiently complete for an agent to select and use 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%, and the schema's parameter descriptions are already thorough (e.g., entities array semantics, models options, _apiKey requirement). The description adds little parameter-specific detail beyond restating that it probes each entity with ai_visibility_check, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes from sibling tools by specifying side-by-side comparison, ranking, and the use of ai_visibility_check underneath. It also provides a concrete use case query, making the purpose unmistakable.

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

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

The description explicitly frames the tool for competitive AI-marketing audits and gives an example, signaling when to use it. It implicitly differentiates from the single-entity sibling ai_visibility_check by stating it probes multiple entities, though it doesn't explicitly state alternatives or exclusions.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description goes beyond annotations by disclosing latency and failure behavior: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' It also describes the return payload in detail, which is essential since there is no output schema. No contradictions with annotations.

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

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

The description is dense but front-loaded with the core purpose, followed by usage, output, and caveats. Every sentence contributes meaningful information (e.g., ecosystem limitation, graceful degradation). It is longer than strictly necessary, but the complexity of the composite tool justifies the length. A shorter version would lose beneficial nuance around failure modes and latency.

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 takes full responsibility for explaining return values, and it does so thoroughly ('summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions'). It also covers edge cases (non-npm ecosystems, partial failures, timeouts). This makes the tool fully interpretable and usable, even without a 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 description coverage is 100% (both package and version have detailed descriptions in the schema). The description does not add new parameter-level detail beyond what the schema already states, such as scoped packages and default version behavior. Since the schema fully documents parameters, a baseline score of 3 is appropriate; the description's overall narrative doesn't need to re-explain them.

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

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

The description opens with a clear, specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call.' It explicitly distinguishes itself from siblings by listing the data sources (deps.dev, bundlephobia) and the types of questions it answers (safe/popular/small). This unambiguously separates it from the other tools in the sibling list.

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

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

Explicit when-to-use is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states an explicit exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This covers both positive and negative guidance, making the tool's scope unmistakable.

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 useful behavioral context by stating that the tool returns metadata including a Feature Service URL intended for use with query_layer/layer_info, which establishes a clear workflow. This goes beyond the safety profile 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 two sentences: the first states the purpose and examples, the second enumerates return fields and the follow-up tool usage. It is concise, front-loaded, and every sentence adds value without redundancy.

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

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

Given the simple search tool with full schema descriptions and rich annotations, the description adequately covers what the tool does, what it returns (name, summary, record_count, owner/org, Feature Service url), and how to integrate with sibling tools. No output schema exists, but the return fields are explicitly listed, making it complete.

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

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

The input schema already provides 100% coverage for all three parameters (query, limit, org_id) with clear descriptions. The description's mention of 'by keyword' aligns with the query parameter but adds no new meaning beyond the schema. Thus, 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 ('Search') targeting a defined resource ('City of Branson GIS open geospatial datasets') and includes concrete examples ('parcels, zoning, public works & city services'). It also differentiates itself from sibling tools by instructing the agent to pass the returned Feature Service URL to query_layer/layer_info.

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

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

The description provides clear usage context: search datasets by keyword for discovery, then pass the returned URL to query_layer/layer_info for actual data. This implicitly directs when to use the tool. However, it does not explicitly state when not to use it or name alternatives like search_within or discover_tools, so it stops short of a 5.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes beyond these by disclosing technical behavior: BGE-base-en embeddings, cosine similarity, 500-character overlapping windows, a 200K character cap, and that longer inputs are truncated and flagged. It also reveals output components (character offsets, similarity scores), providing a complete behavioral picture.

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

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

The description is well-structured and efficient, starting with an action-oriented purpose, then usage context, a pairing note, and technical specifics. No sentence is wasted; even the technical details (embeddings, windows, cap) serve to set expectations. It is dense but not bloated.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers all essential aspects: what it does, when to use it, how it behaves technically, what it returns, and its limitations. It even explains the truncation behavior. This is complete enough for an agent to invoke the tool correctly and interpret results.

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

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

The schema has 100% coverage with descriptions for all three parameters, including an example for 'query'. The description reinforces this by referencing 'the text you already pulled' and the 200K cap, but it does not add substantial meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting for parameter 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 opens with a specific verb and resource: "Semantic search INSIDE a fetched record." It clearly distinguishes from siblings by contrasting with ask_pipeworx_grounded and noting that this tool searches within already-pulled text rather than querying a source directly. The purpose is unambiguous and immediately obvious.

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 provided: "Use when the record is too big to cram into the prompt." It also explains the relationship with a sibling tool: "Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document." This gives clear context for when to choose this tool over alternatives.

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

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

Beyond the annotations, the description discloses meaningful behavioral traits: the OAuth account requirement and persistence limitation for anonymous/BYO users, phone verification for SMS, the 10/day cap, and the always-on feed behavior. It also notes the returned subscription id. There is no contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

The description is dense and front-loaded with the main purpose, then systematically covers supported types and delivery channels. It is a single long paragraph but every clause contributes useful information. A bit of restructuring could improve scannability, but it is not excessively verbose.

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

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

The description covers the purpose, prerequisites, subscription types, delivery options, and return value. It omits the webhook delivery channel and two subscription types from the main text, but the schema fully documents those. Overall, the description is sufficient for an agent to invoke the tool correctly when combined with structured schema data.

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

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

With 100% schema description coverage, the baseline is 3. The description adds extra semantic value for sec_8k (e.g., items:["5.02"] = officer change), polymarket_edge (topic:"fed"), and fred_series (series_id:"UNRATE"). However, it omits patent_grant and clinical_trial from its examples, though those are covered 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 clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), and it explicitly mentions the return value (subscription id). It also distinguishes itself from sibling tools like list_subscriptions and unsubscribe by emphasizing the creation aspect and the persistent feed.

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

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

The description provides strong usage context: it requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels including how to pull from the always-on feed. It does not explicitly name alternatives or exclusions, but the use case and prerequisites are clear enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds context by detailing the output structure (category-bucketed questions, exact tool + argument shape) and the behavior of full spread vs topic-focused calls. No contradictions, but it doesn't disclose details like response size or pagination, hence a 4.

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

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

The description is longer than the bare minimum but every segment serves a purpose: example phrasings, category list, output detail, and usage modes. It is front-loaded with user intents and well-structured, though the initial list of example queries could be slightly trimmed without losing core meaning. Still concise and effective.

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 one optional parameter, no output schema, and rich annotations, the description fully covers what the tool does, what it returns, how to call it, and when to use it. It also connects to related meta-tools, making it a complete onboarding resource.

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 covers the topic parameter 100% with allowed examples and guidance. The description reinforces this by showing no-argument vs topic-focused usage and adding concrete topic values ('finance', 'pharma', 'betting'). Since the schema already covers the parameter well, the description's additional value is modest but useful, warranting a 4.

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

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

The description clearly states the tool's role as an onboarding entry point that suggests example questions, using specific verbs like 'Returns category-bucketed example questions' and 'the exact tool + argument shape.' It distinguishes itself from sibling tools by instructing to use it FIRST when unfamiliar with Pipeworx, making its purpose unambiguous.

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

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

The description explicitly says to use this tool FIRST when you don't know what Pipeworx can do, and to learn how to call meta-tools. It provides clear context on when to use it but lacks explicit exclusions or direct comparisons to alternative tools like discover_tools, so it falls slightly short of full alternative guidance.

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

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

Annotations already indicate this is a non-read, non-destructive, idempotent operation. The description adds valuable behavioral detail: the row is deactivated rather than deleted, and historical events stay available. This goes beyond annotations and clarifies the soft-delete side effect.

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 primary action, and each sentence adds distinct value: what is done, who can do it, and what happens to the row. No wasted words.

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

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

For a single-parameter mutation with strong annotations and no output schema, the description covers the essential context: ownership, deactivation behavior, and historical availability via recent_alerts. Nothing critical is missing.

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

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

The input schema already fully describes the 'id' parameter (uuid returned by subscribe). The description's 'by id' adds no new semantics. With schema coverage at 100%, 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 starts with a specific verb+resource: 'Cancel a subscription by id.' It clearly distinguishes from sibling tools like subscribe and list_subscriptions by focusing on cancellation and ownership enforcement.

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

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

Provides clear usage context: 'Ownership is enforced — you can only cancel your own subscriptions' and notes that historical events remain available via recent_alerts. This implies when to use the tool and hints at alternatives, though it doesn't explicitly name 'use list_subscriptions to view your subscriptions'.

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 annotations by explaining return verdict possibilities, the critical distinction between 'could_not_verify' (did not happen) and 'unsupported' (no source exists), and the error structure. It also clarifies the grounded vs structured pipeline and citation behavior, adding valuable operational context.

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

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

The description is long but well-structured, opening with trigger phrases and then flowing through usage, routing, return values, and caveats. Every sentence adds necessary information for a complex tool, though a trim of some informal phrasing could make it slightly tighter.

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

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

The description is comprehensive: it explains what the tool does, when to use it, the routing logic, the full return structure (verdict types, value, citation, reasoning), and how to interpret error cases. With no output schema, this rich description fully compensates for missing structured return docs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful detail beyond the schema: examples for the 'claim' parameter and a thorough explanation of 'tolerance_pct' override behavior including default cap and hallucination-detection use case. This extra context justifies a 4.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with specific verb 'verify' and resource 'authoritative sources'. It distinguishes itself from siblings by stating it replaces 4–6 sequential calls and by enumerating the exact claim categories it handles, making it 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and details the routing logic for company-financial vs other claims. It also clarifies the consolidated nature ('Replaces 4–6 sequential calls'), giving clear context on when to prefer this tool over alternative sequences.

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