Arcgis Durham

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: the default model is free, and providing `_apiKey` triggers calls to Anthropic with direct billing to the user ('you pay Anthropic directly'). It also discloses the return structure. This goes beyond the annotations without contradicting them.

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

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

The description is compact and well-structured. It leads with the core purpose, then covers configuration and return format, and ends with use cases. Every sentence provides useful information without redundancy, 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 (4 parameters, no output schema), the description adequately covers the response format and key behaviors. It explains default behavior, optional configuration, and typical applications. It does not detail error handling or rate limits, but such specifics are not essential for tool selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances understanding by explaining that the default model is Workers AI Llama-3.3-70b (free) and that `_apiKey` is required to probe Anthropic, clarifying the relationship between `models` and `_apiKey`. It also mentions the per-model return object, which 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 clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb (probe) and resource (LLMs), and distinguishes itself by focusing on visibility scoring across models. The output format is also mentioned, making it easy to understand the tool's unique value.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or state when not to use the tool, but the context is well-defined. It also explains how to request additional models, which is a practical usage 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 read-only, idempotent, open-world. The description adds behavioral context: routes across 5,529 tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier with one fast call. 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 long but front-loaded with the priority statement and alternates between guidance, examples, and exceptions. Every sentence contributes something distinct, though the final sentence on news coverage could be folded in; overall it's 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?

Despite having no output schema, the description specifies the return format (structured answer with citation URIs). It covers domain scope, trigger phrases, examples, default status, and upgrade paths to sibling tools, making it highly complete for the agent.

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

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

Schema coverage is 100% with the 'question' parameter and aliases fully described. The description adds examples of acceptable queries but no new syntax or constraints, so it meets the baseline without going beyond.

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

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

The description clearly states the tool answers factual questions with authoritative structured data and citations, routing to thousands of sources. It specifies a verb ('routes', 'returns') and resource, and distinguishes from web search and sibling tools like ask_pipeworx_grounded.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also names alternatives and when to step up: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'.

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

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

The description goes beyond annotations by disclosing the beta status, the existence of candidate routing improvements (none active currently), and that it currently behaves identically to ask_pipeworx. It also clarifies 'Falls back to nothing' meaning it is a full working router, not a degraded mode. This adds useful context not captured by the safe-read 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 moderately concise, front-loading the beta nature and key facts in the first sentence. Each subsequent sentence adds value (tool count, response shape, candidate status, usage guidance, error clarification). It could be tightened slightly but remains efficient for the nuance it must convey.

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 as a beta router with no output schema, the description covers the essential aspects: relationship to ask_pipeworx, current parity, usage, and evaluation purpose. It lacks explicit return format details, but the phrase 'same response shape' adequately points users to the stable tool. Completeness is sufficient for an experimental variant.

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, all as aliases for 'question', so the description does not need to repeat that. It does add the context that the arguments are identical to ask_pipeworx, reinforcing the schema's coverage. No extra semantic detail is necessary given full schema clarity.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router that handles 5,529 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by noting the experimental routing improvements and current inactive state.

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 it exactly like ask_pipeworx when you want the newest routing.' It also explains the comparative purpose against the stable router. However, it does not explicitly mention when not to use it or contrast with other sibling tools like ask_pipeworx_grounded.

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

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

Beyond the readOnly/OpenWorld/idempotent annotations, the description discloses the explicit refusal mechanism with refusal_reason enumerations, the return structure including {answer, evidence, confidence, source, fetched_at}, and the constraint that answers are extracted ONLY from tool results, which is a substantive behavioral addition.

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 packed with useful details and front-loaded with the key differentiator; each sentence serves a purpose. It avoids fluff while covering purpose, process, output, failure modes, and usage guidance.

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

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

Despite having no output schema, the description compensates by explicitly describing the success object and refusal object fields, along with failure reasons. It also covers cost comparison and use cases, making it complete for a tool of this complexity.

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

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

The input schema already fully documents all six parameters (aliases for question) with 100% coverage, so the description's lack of additional parameter detail is acceptable. The description refers to 'question' but adds no syntax or format 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 this is a 'hallucination-resistant answer mode' that extracts answers using only tool result contents, distinguishing it from the sibling ask_pipeworx. It names the specific resource (Pipeworx) and the key behavior (grounded extraction) with a clear verb.

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

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

The description explicitly states when to use it ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the trade-off of one extra LLM call. This provides clear selection criteria relative to its sibling.

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, detailing the resolver's confidence levels, fan-out behavior, short-circuit statuses for low-confidence or closed markets, tradeability warnings, and handling of rate limits (GDELT 429). It also discloses that medium/low matches may still surface fields and recommends inspecting the resolver contract before trusting analysis. This aligns with the openWorldHint and readOnlyHint, adding rich behavioral context.

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

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

The description is long but well-structured with capitalized section headers, front-loading the purpose and usage. While every section adds valuable information, the overall length is extensive; it could potentially be trimmed without losing critical details, but the clear organization mitigates the 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?

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the return structure (market, analysis, evidence, resolver contract, parent_event), safety behaviors, and edge cases. It even covers cancellation-rule risks and how to interpret low-confidence matches, making the description self-sufficient for an agent to 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?

While the schema fully describes each parameter, the description adds substantial meaning: it specifies accepted formats for `market` (slug/URL/question text), the `depth` semantics (quick vs thorough with fan-out implications), and the `include_raw` trade-off (response size vs raw payloads). The classifier list and fan-out examples further clarify how inputs map to behavior, going well 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly stating the verb (Research), resource (Polymarket bet), and the mechanism (Pipeworx data). It also specifies accepted input formats and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides explicit use-case triggers ('Use for...') and detailed fan-out examples for different bet categories, giving strong guidance on when to apply the tool. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, which would fully meet the 5-level criteria for usage guidelines.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. This goes beyond what annotations provide, though it could mention rate limits or error handling.

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 moderately long but every sentence contributes useful information. It front-loads trigger phrases and the key 'ALWAYS PREFER' instruction, then logically details type-specific behavior, sorting, and output. No filler or redundancy; the structure is effective for a tool with two distinct entity types.

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 two parameters and no output schema, the description covers the essential context: usage scenarios, data sources, metric sorting, and return format (paired data + citation URIs). It omits edge cases like pagination or error conditions, but given the tool's simplicity and rich annotations, the description is sufficiently 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%, so the baseline is 3. The description enriches parameter semantics by explaining what each type value means (company vs. drug) with specific data sources and metrics, and gives concrete examples for values (tickers/CIKs vs. drug names). This adds meaningful guidance 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 is exceptionally clear: it lists concrete trigger phrases, states the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, and differentiates itself from sequential single-pack lookups. It names specific data sources and output characteristics, leaving no ambiguity about its purpose.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains that it replaces 8–15 sequential lookups. It also implies when not to use it (for single entity lookups), providing clear situational guidance without naming sibling tools, which is sufficient.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description significantly augments them: account/paid-plan requirements, 15-60s latency, gap[] behavior ('never invented'), fetchable citation_uri, contradictions[] for standard/thorough, and semantic excerpting. No contradiction with annotations exists.

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

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

The description is long, but the tool is complex and the length is justified. It is front-loaded with the most critical operational constraint (account required), then moves through core purpose, usage guidance, and behavioral details. Some redundancy exists with the schema text, but overall each section earns its place.

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

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

With no output schema present, the description fully documents the return structure: findings packet with verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], and contradictions[]. It also covers auth, latency expectations, data-source scope, and exclusion cases, making it nearly complete for an agent to decide and invoke.

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

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

Schema coverage is 100% and the schema already explains depth and question in detail. The description adds contextual semantics beyond the schema: depth:'thorough' requires a paid plan, latency varies by depth, and the second-hop iteration behavior ('gap recovery', 'chases the best leads') gives practical meaning to the depth parameter.

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

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

The description clearly identifies the verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with an explicit statement that it is 'NOT open-web search.' It also distinguishes itself from siblings by contrasting with ask_pipeworx for single lookups and current-news scenarios.

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

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

Usage guidance is exceptionally explicit: 'Best for broad/multi-part questions over structured data' states when to use it; 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx' state when not to. It even notes account tiers and instructs non-signed-in users to use ask_pipeworx instead.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the bar is lower. The description adds valuable behavior: returns top-N results with names, descriptions, full schemas, and curated examples, ready to call directly with no second lookup. It also clarifies that results are directly invocable.

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 ideal but front-loaded with purpose and usage. The domain list is arguably redundant with the schema examples but provides useful scope; each sentence contributes a distinct function (purpose, when-to-use, return format, first-step advice).

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

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

Despite no output schema, the description fully explains the return value: top-N tools with names, descriptions, and full input schemas, ready to call. Combined with annotations covering safety and idempotency, this is complete for a discovery tool.

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

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

Schema coverage is 100%, with all six parameters documented including aliases and limit. The description adds marginal context ('describing the data or task' maps to query; 'top-N' maps to limit), but the schema already does the heavy lifting, 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 opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a discovery/browsing meta-tool versus siblings like search_datasets or query_layer by listing the action verbs (browse, search, look up, discover) and the domain 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?

It explicitly states 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This gives clear context, though it doesn't explicitly name alternative tools or a when-not-to-use beyond implying if you want one answer.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses detailed behavioral traits: the exact return fields (cik, recent_filings, fundamentals, patents, news, LEI), the sorting and limit of filings (up to 5), the patent API sunset and soft-fail behavior, and the GDELT→GNews fallback. It also notes input constraints like zero-padded CIK. This is rich, valuable transparency that far exceeds 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 a dense single paragraph that packs many details: examples, output fields, fallbacks, and limitations. Every clause adds information, but it could benefit from bullet points or a cleaner structure. It is not overly long given the complexity, and the most important usage directive ('ALWAYS PREFER...') is placed upfront, which aids agent decision-making.

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

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

For a tool with no output schema, the description comprehensively covers what the tool returns, including field names and ordering. It accounts for edge cases (patent API sunset, GDELT→GNews fallback, CIK formatting), and it clarifies limitations (names not supported). This is fully complete for an agent to invoke the tool and interpret results without surprises.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description adds value by providing concrete examples ('AAPL', '0000320193'), emphasizing the zero-padded CIK requirement, and clarifying that names are not supported with a pointer to resolve_entity. It also notes that only 'company' is supported today. This enriches the schema semantics without repeating verbatim.

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

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

The description clearly states the tool's purpose as a 'full cross-source profile of a US public company in ONE parallel call.' It gives specific examples ('Tell me about X', 'research Acme', 'brief me on Tesla') and distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by directing name-based requests to resolve_entity instead. This clearly separates it from related tools like compare_entities and resolve_entity.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear alternative for name inputs: 'use resolve_entity first if you only have a name.' This tells the agent exactly when to invoke this tool and when to use a sibling tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds useful context about when deletion is appropriate, but does not go beyond annotations to explain side effects or error handling. It is consistent with annotations, so 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 concise sentences, front-loaded with the primary action, followed by usage contexts and sibling references. Every word earns its place; no redundancy or filler.

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

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

For a simple one-parameter destructive tool with strong annotations and full schema coverage, the description provides sufficient context for an agent to select and invoke it. It could mention what happens on success or when the key is missing, but this is not critical given its simplicity.

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

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

Schema coverage is 100% ('Memory key to delete' fully describes the only required parameter). The description adds no extra parameter-specific details, which is fine since the schema is complete. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and the exact resource. It differentiates from siblings by explicitly pairing with 'remember' and 'recall', making its role distinct.

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 contexts ('Use when context is stale, the task is done, or you want to clear sensitive data') and references related tools ('Pair with remember and recall'). It does not explicitly state when not to use it, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the internal behavior (fetches page, extracts title/description/key links) and the output format ('single text blob ready to drop at site-root/llms.txt'). This goes beyond annotations without contradicting them.

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

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

The description is three sentences, with each sentence serving a clear purpose: stating the core function, describing the process/output, and listing use cases. There is no wasted wording, and the structure is front-loaded with the most important information first.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description is complete. It explains the purpose, the output format, and the intended use cases. Annotations cover safety, so no further behavioral information is needed. The description fully compensates for the lack of an output schema by stating the exact output type.

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

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

Schema description coverage is 100%, with both parameters (url and max_links) already described in the schema. The description does not add any parameter-specific details beyond what the schema provides (e.g., it doesn't mention max_links). Since the schema carries the full burden, the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Generate'), a clear resource ('a production-ready llms.txt file for any URL'), and outlines the process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It clearly distinguishes itself from sibling tools by focusing on generating the llms.txt file itself.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') which clearly indicate when to use the tool. However, it does not mention any exclusions or alternative tools, so it stops short of the full 'when/when-not/alternatives' guidance.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context about what 'schema' means here, listing fields, geometry type, record count, and capabilities, which goes beyond the minimal annotation information.

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 sentence, front-loaded with the verb 'Get', and contains zero filler. Every word contributes to clarity and the output contents are compactly listed.

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 parameter and no output schema, the description fully specifies the expected return values (fields, geometry type, record count, capabilities). There are no missing behavioral or safety details that could prevent correct invocation.

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

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

The schema provides 100% coverage of the single 'url' parameter, including type, description, and an example. The description only repeats that the operation is 'by url', adding no new semantic detail beyond what is already in the schema. Baseline 3 is appropriate because the schema handles the 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 uses the specific verb 'Get' and clearly identifies the resource: 'an ArcGIS Feature/Map Service layer's schema by url'. It also enumerates the exact output contents (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that retrieve actual data.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. The use case is implied by the purpose 'Get ... schema', but there is no direct guidance such as 'use query_layer for data queries'.

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, and idempotentHint=true. The description adds useful context about caller-specific scoping and the exact return fields, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. No unnecessary words or repetition.

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

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

Despite no output schema, the description explicitly lists all return fields. Combined with rich annotations and a simple optional parameter, the description provides complete context for correct usage.

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 one parameter (include_inactive) has a clear description. The tool description implies the default active-only behavior but doesn't add significant new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and details the return fields. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

It explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use context. It doesn't name alternative tools explicitly, but the guidance is actionable.

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

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

The description goes well beyond the annotations (which are all false and uninformative). It discloses the claim_token workflow, rate limiting (5/day), quota exemption, daily digest behavior, and roadmap impact. It also clarifies the expected input style (describe in terms of Pipeworx tools, not user prompts). 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 longer than average but every sentence earns its place: purpose, usage, exclusions, token behavior, and operational details. It is front-loaded with the core purpose and then flows logically. Slightly dense as one block, but structured effectively.

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 feedback tool with no output schema, the description covers all essential aspects: purpose, when to use, what to include, token retrieval, rate limits, quota impact, and exclusions. The nested context object and enum are documented in the schema, and the description fills the remaining contextual gaps. It feels complete without being redundant.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: it explains how to use claim_token (pass back later to read status), clarifies that message should be specific and not paste user prompts, and maps type values to feedback categories. This elevates it above baseline, though it doesn't elaborate on the structured context object 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this tool from research/query siblings by framing it as feedback, and enumerates concrete use cases (bug, feature/data_gap, praise). This clearly differentiates it from tools like ask_pipeworx or discover_tools.

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

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

Explicit when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a strong exclusion: 'if the tool came from a different MCP server ... file it with that server instead,' plus a disambiguation rule for identifying Pipeworx tools. This is model-tier 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds meaningful behavioral context: it is "Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)." It also discloses caching behavior: "Cached 5min-1h depending on window." This adds transparency about data provenance, privacy, and freshness, which goes beyond simple read-only intent.

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 front-loaded. The first two sentences establish purpose and output. The bullet-style list of use cases is efficient and scannable. The final sentence adds essential behavioral context (data source, privacy, caching) without fluff. Every sentence contributes necessary information.

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

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

Despite having no output schema, the description tells the user what to expect: "top tools, top packs, and total call volume" and internally "just (pack, tool, count)." It also covers caching, data source, and non-PII. For a simple read-only tool with one optional parameter, this is complete enough to set accurate expectations. The absence of an output schema is compensated by the clear description of the return shape.

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

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

The schema already describes the window parameter fully with enum values and meaning: "24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand." The description merely restates the window options with no additional semantic detail. The schema covers 100% of parameter documentation, so a baseline of 3 is appropriate.

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

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

The description opens with a clear, specific statement: "What other AI agents are calling on Pipeworx right now." It then details the return content: "top tools, top packs, and total call volume over a recent window." This clearly distinguishes it from siblings like ask_pipeworx (which likely answers questions) and discover_tools (which might list available tools), as it focuses on aggregated usage trends.

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

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

Provides explicit usage scenarios: "Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need." This is concrete guidance on when to invoke the tool and what value to expect. Though it doesn't name alternatives, the context of siblings plus the clear use cases make usage guidelines strong.

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

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

Beyond annotations (readOnly, idempotent), the description discloses rich behavioral details: the >3pp deviation threshold, the ≥0.30 Jaccard similarity filter, placeholder fraction >20% nulling, and the fill check that warns 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it'. It even explains output structure and edge cases, far exceeding the annotations' safety profile.

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

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

Although dense, every sentence earns its place. The description is structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. The length is justified by the tool's complexity and the need to convey three modes, filters, and fill-check caveats without ambiguity.

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 zero output schema, the description compensates by describing response fields ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)') and the partition_check output. It also covers prerequisites, mode-specific behavior, filters, and trading caveats. This is fully complete for a complex tool with no output schema.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains how the event parameter drives 'walks child markets, checks date-axis / threshold-axis ordering AND computes partition_check', and how topic 'searches related events across the platform, flattens markets, runs the comparator'. This transforms the parameters from simple strings into functional modes with concrete examples.

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

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

The description opens with a specific verb-resource pair ('Find arbitrage opportunities on Polymarket') and explains the method ('monotonicity violations + partition-sum checks'). It clearly distinguishes this from sibling tools like polymarket_edges or polymarket_fill_risk by its dual-mechanism approach, and further details modes (event, topic, trending_scan). This is a textbook example of purpose clarity.

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 guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), providing a clear when-to-use vs alternative hierarchy.

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 provide readOnlyHint and idempotentHint, but the description adds substantial behavioral context: it details the three model families, the edge_pp_net calculation, slippage handling, 24h-move warning, the exclusion of Fed candidates with rationale, response diagnostics, and 1h caching. This goes well beyond the annotations and provides valuable operational insight.

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 (~400 words) but densely structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL). Every sentence contributes unique detail (model families, filters, response fields, caching). It is well-organized but arguably verbose; could be trimmed for clarity, so a 4.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is exhaustive: it specifies response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields, segment gates, filtering knobs, and caching behavior. It even explains why segments may be empty and what diagnostics reveal. Without an output schema, this description carries the full burden and meets it.

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

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

The input schema already has 100% description coverage, but the description adds meaning beyond the schema: it explains tradeable-edge knobs (min_liquidity/max_spread_pp), clarifies that min_partition_leg_kelly applies to per-leg Kelly rather than parent-level, and discusses the design of slippage_pp (Polymarket has zero fees, etc.). This significantly enhances parameter understanding.

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

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

The first sentence clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This identifies the verb (scan/return), resource (Polymarket markets), and differentiates from siblings like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx data disagreement.

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

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

States 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This clearly conveys when to use the tool (opportunity discovery) but does not explicitly name when not to use it or alternatives. The context is strong but lacks explicit exclusions, so a 4.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds substantial behavioral detail: history depth is bounded by a 60-day TTL, snapshot gaps exist when no cache-miss occurred, decay is computed from daily closes net of default slippage, and the response format is fully described. This far exceeds what annotations alone 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?

Though lengthy, the description is perfectly structured with clear sections (purpose, args, response, limits). Every sentence adds unique information—no filler or redundancy. The response format is enumerated legibly, and limits are explicitly called out. The front-loaded first sentence immediately establishes the tool's purpose, making the length 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 tool's complexity (time-series data, snapshot lifecycle, edge decay) and absence of an output schema, the description fully compensates. It explains the response structure (tracked[], expired[], snapshot_dates[]), the meaning of each field, the calculation methods, and the TTL/gap limitations. There are no obvious gaps in what an agent would need to know for correct invocation and interpretation.

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 describes both parameters with 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by introducing the concept of 'snapshot family' for the window parameter and explaining that days controls the lookback with default/max values (slightly different from schema's clamp range). It also clarifies how the parameters relate to the telemetry logic, adding value.

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 an edge persistence and decay telemetry tool, answering a specific question: "how long has this edge existed and is it shrinking?" It distinguishes itself from raw edge tools (like polymarket_edges) by focusing on historical snapshots and trend analysis, and explicitly contrasts a fresh wide edge with a 3-week-old one—making its unique value 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?

The description provides clear context for when to use this tool: when edge age and decay matter. It implies it should be used over raw edge tools for understanding persistence, but it does not explicitly name alternatives or state 'use when X, not when Y'. The contrast between fresh and old edges effectively guides selection, but explicit exclusions are missing.

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, destructiveHint=false; the description does not contradict these and adds meaningful behavior: it 'walks the ladder', returns top_of_book/vwap/slippage/verdict, and highlights forced_directional_risk and thin_legs. It also clarifies size_usd semantics (max spend vs target proceeds vs settlement notional) and the dominant loss mode.

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

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

The description is a dense single paragraph without bullet points or section breaks, but it is front-loaded with the core purpose. Every sentence adds operational or risk information, though structural formatting would improve scanability. The length is justified by the tool's complexity (two modes, many return fields).

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

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

With no output schema, the description details return fields for each mode (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict; and theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs). It also covers parameter validation ('REQUIRES one of') and use-case context, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters with descriptions, but the description enriches them with mode-specific semantics: the difference between `market` and `event`, how `side` defaults differ by mode, and how `size_usd` is interpreted (spend, proceeds, settlement notional). It also notes default value and clamp range, adding value beyond the schema.

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

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

The description opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth' – a specific verb+resource+mechanism. It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges as signals this tool should precede.

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

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

It explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the failure mode (partial basket fills convert arb into unhedged directional position). It also defines two modes (single-market and basket) with conditional parameters.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description goes far beyond these by detailing compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs matched_pairs:0 with skipped_cross_type:0), temporal_alignment semantics, and skipped_cross_type/subtype counters. This discloses edge-case behavior and output variations not visible in the annotations.

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

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

The description is long but well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) that front-load the core purpose. Every sentence carries either functional or cautionary information; there is no fluff. However, it is dense and could be slightly tightened with bullet points, so it does not reach a perfect 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?

With no output schema, the description fully explains the response components: per-leg prices, spread values, compatibility_warning cases, temporal_alignment, and skip counters. It also covers caveats like unmatched events and the rarity of real spreads. For a tool of this complexity, this is comprehensive and leaves no major gap.

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

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

Schema coverage is 100% with each parameter described, so baseline is 3. The description adds meaningful interaction semantics: explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and it lists all valid topic values. It also explains that topic mode auto-fetches matching events, which is not in the schema's individual parameter descriptions. This pushes it above baseline.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue nature and matching resolving question. The two-mode structure (topic shortcuts vs explicit ticker/slug) further clarifies the tool's scope.

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

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

The description explicitly specifies when to use each mode: topic shortcuts for pre-mapped macros, explicit ticker/slug for custom pairings. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable' and explains that the spread is a real signal only when bet shapes are equivalent. This provides clear when-to-use and when-not-to-use guidance, rivaling the TDQS 4.3 example.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context by stating it returns attribute rows and geometry, and mentions pagination via offset and limit. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core action and parameter list. Every sentence adds value, and there is no redundancy or filler.

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

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

Given six parameters and no output schema, the description covers the tool's purpose, key parameter behaviors, return type (attribute rows and geometry), and a practical sampling pattern. It could mention error handling or response structure, but it is sufficient for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with descriptions for all six parameters. The description adds little semantic value beyond the schema—it reiterates 'SQL-like where' and 'comma-separated out_fields' which are already in the schema. The sampling tip is useful but more about usage than parameter meaning.

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 'Query an ArcGIS Feature Service / Map Service layer by its url', providing a specific verb and resource. It distinguishes from sibling tools like search_datasets (which finds datasets) and layer_info (which likely describes metadata) by focusing on querying layer data.

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

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

The description provides workflow context by noting the URL comes from search_datasets, and includes explicit usage tips such as using where='1=1' with out_fields='*' to sample. While this gives clear context, it does not explicitly exclude when not to use the tool or name alternative tools for different scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the conditional behavior of retrieving vs listing all keys. 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 four sentences long, front-loaded with the primary action, and every sentence earns its place: action, use case, scope, and pairing with sibling tools. No redundancy or filler.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers the tool's function, usage context, scoping, and relationship to related tools, leaving no significant gaps for an agent to select and invoke it correctly.

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

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

The schema description already covers the single parameter's semantics: 'Memory key to retrieve (omit to list all keys)'. The description reiterates this and provides illustrative examples of key values, but does not add new syntactic or format details beyond what the schema already specifies. With 100% schema coverage, 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 ('Retrieve') and clearly identifies the resource ('a value previously saved via remember') as well as the alternative mode ('list all saved keys'). It explicitly distinguishes itself from sibling tools by referencing remember (save) and forget (delete).

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 an explicit use case: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explains when to use the key argument vs omit it, and names the paired tools (remember, forget), making the usage context fully clear.

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

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

The description discloses important behavioral traits beyond annotations: the persisted feed nature, the mark_read side effect (which modifies read state, explaining that the next call only shows newer ones), the return format, and polling suitability. This goes well beyond the readOnlyHint and idempotentHint annotations, providing actionable 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 front-loaded with the main action, and each subsequent sentence adds essential detail (return format, filters, mark_read behavior, polling, alternative endpoint). It is concise, with no redundant or filler information, and well-structured for an agent to parse.

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 five parameters, no output schema, and the presence of annotations, the description covers the behavior comprehensively: it explains what is returned, how filtering works, the mark_read side effect, and offers a URL for non-tool access. This is sufficient for an agent to understand the tool's full context.

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

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

The schema already documents all five parameters with descriptions, achieving 100% coverage. The description mentions filtering by type and since, and setting mark_read, but these are restatements of schema properties rather than new semantic insights. It does not add detail like parameter formats or behavior beyond what the schema offers, so the baseline 3 applies.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', and further specifies return value elements (source, citation_uri, raw event payload). It is distinct from sibling tools like list_subscriptions and recent_changes, 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 gives clear context: it indicates that polling works fine and mentions an alternative access via GET registry.pipeworx.io/alerts.json for scripts/dashboards. However, it does not explicitly contrast with sibling tools or state exclusion criteria beyond the URL alternative, missing a direct 'when to use vs alternatives' statement.

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 and idempotent. The description adds behavioral details beyond annotations: fans out to multiple sources, GDELT preferred with GNews fallback on rate limits/5xx, USPTO soft-fail, and `since` date formats. No contradiction found.

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

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

Description is detailed but information-dense, covering query examples, source fan-out, parameter syntax, return shape, and sibling alternative. Slightly long but every sentence adds value for a multi-source 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?

No output schema exists, so the description must explain return values—and it does: structured changes[] grouped by source, total_changes count, and citation URIs. It also covers sources, fallback, time syntax, and sibling differentiation, making it fully self-contained for tool selection.

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

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

Schema covers all parameters with descriptions (100% coverage), but the description adds concrete examples for `since` (ISO date vs relative shorthand) and clarifies `value` accepts ticker or CIK. This enriches schema semantics beyond the structured definitions.

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

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

Description clearly states the tool provides a change feed for a company over a time window, with specific query examples. It explicitly distinguishes from entity_profile, making the purpose unambiguous and well-differentiated from siblings.

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

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

Provides explicit usage scenarios ('What's new with X') and explicitly directs users to entity_profile for static profiles. It also explains fallback behavior (GDELT→GNews, USPTO soft-fail), adding practical guidance for when to use this tool.

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

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

Beyond annotations, the description discloses key-value scoping by identifier and persistence behavior (24 hours for anonymous sessions, persistent for authenticated users). This adds context not present in annotations.

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

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

The description is compact, with each sentence serving a purpose: definition, usage examples, storage mechanics, persistence details, and sibling pairing. 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 simple two-parameter tool with no output schema, the description covers what it does, when to use it, persistence semantics, and related tools, making it entirely actionable.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces key-value pairing but adds little beyond the schema's explicit 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 saves data for later reuse, using the specific verb 'Save' and resource 'data'. It also distinguishes sibling tools by explicitly pairing with 'recall' and 'forget'.

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

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

Provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also mentions persistence differences and names recall/forget 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?

The description discloses rich behavioral details beyond annotations: internal cascading through multiple endpoints, graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), source labeling for every identifier, and explicit reporting of unresolved identifiers under `unresolved`. These details inform the agent about expected behavior, failure handling, and output structure, complementing the annotations.

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

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

The description is lengthy but structurally organized: example queries, core purpose, usage directive, then detailed SUPPORTED TYPES. Every section adds value, especially the degradation and unresolved handling. It is slightly verbose in the example list but overall the detail is warranted for a multi-type, multi-source tool. Front-loading the core purpose aids quick comprehension.

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

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

Even without an output schema, the description fully covers return value semantics: identifiers, source labels, unresolved placeholders, and citations. It addresses both supported types comprehensively, including fallback behavior and internal lookups. This is a complete picture for an agent to invoke the tool and interpret results. The only missing aspects are auxiliary like rate limits, but these are not critical for a 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 input schema has 100% field coverage, so the baseline is 3. The description adds meaning by explaining what each entity type resolves to (company: CIK/ticker/LEI/FIGI with source labels; drug: RxCUI/ingredient/brand with citation). It also clarifies accepted input formats ('ticker (AAPL), CIK (0000320193), or name'), enriching the schema descriptions and giving the agent deeper context for parameter values.

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 leads with a clear verb-object statement: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It immediately distinguishes itself from siblings like entity_profile by framing the tool as the first-stop for name-to-ID conversion, with concrete example queries. The supported types (company, drug) add further specificity.

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

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

The description gives explicit usage context: "Use FIRST whenever you have a name but need an ID." This is a strong directive for when to invoke the tool. However, it does not mention alternatives or case where another tool would be preferred (e.g., already have an ID), so it lacks exclusions. Still, the guidance is clear and actionable.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description needn't repeat safety. It adds useful behavioral context: internally probes each entity via ai_visibility_check, ranks results, and returns per-entity score/confidence/signal density. It does not mention rate limits or API key requirements, but those are 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?

Three sentences with no redundancy: first states core behavior, second gives a concrete example use case, third describes return value. Front-loaded and efficient.

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

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

No output schema, but the description specifies the return format (ranked list with score, confidence, signal density). It covers the workflow, use case, and internal mechanics. With strong annotations and full schema coverage, the description is complete for a tool of this complexity, though it could explicitly mention model/apiKey options.

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 all four parameters are well-documented. The description adds minimal parameter nuance beyond the schema (e.g., first entity as subject is in schema). Baseline 3 is appropriate because the schema carries the load.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and highlights most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by focusing on competitive AI-marketing audits.

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

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

The description gives a clear use case (competitive AI-marketing audits) with an example question, and implicitly contrasts with ai_visibility_check for single-entity checks. However, it does not explicitly state when not to use this tool or name alternative tools for other scenarios.

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

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

The description discloses behavioral traits beyond the annotations: it fans out across two services, partially fails gracefully, notes a 5-30s delay for bundlephobia's first measurement, and mentions the sources_failed field. This adds useful context not present in readOnlyHint/idempotentHint.

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

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

The description is dense but well-structured, with each sentence serving a distinct purpose: core function, usage guidance, return fields, ecosystem scope, and failure behavior. 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?

Despite lacking an output schema, the description enumerates all key return fields (is_latest, license, bundle_kb, etc.), explains partial failure behavior, and defines the ecosystem scope. This makes the tool's behavior self-contained and understandable for an agent.

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

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

Schema description coverage is 100%, so the parameters (package, version) are already well documented in the schema. The description adds no new parameter-level detail beyond what the schema provides, meriting the baseline score of 3.

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

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

The description clearly states the tool performs a composite check combining deps.dev and bundlephobia data for npm packages. It uses a specific verb 'check' and resource 'npm package', and its focus on dependency quality distinguishes it from sibling research tools.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a clear alternative for other ecosystems ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), showing 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by specifying the exact return fields (name, summary, record_count, owner/org, Feature Service url) and the hand-off pattern, which is strong behavioral context.

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

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

Two sentences, no filler: the first states the primary purpose and scope, the second lists return contents and downstream usage. Every word earns its place.

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

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

The description is complete for this tool: it covers what it searches, what it returns, and what to do with the results. No output schema exists, so the explicit return-value listing is necessary and sufficient. Optional parameters are already fully documented in the schema.

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

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

The input schema has 100% description coverage for all three parameters with clear examples and descriptions. The description adds little parameter-specific detail beyond reinforcing that the query is keyword-based, so the baseline score 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 uses a specific verb ('Search') and names the exact resource (Durham City-County GIS open geospatial datasets) with example topics. It also clearly differentiates from siblings by identifying query_layer / layer_info as downstream consumers of the returned Feature Service url.

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 (find datasets by keyword) and explicitly directs users to query_layer / layer_info for subsequent operations. It lacks a formal 'when not to use' statement, but the alternative chaining is concrete and helpful.

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

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

Beyond the readOnly/idempotent annotations, the description reveals concrete algorithmic behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation and flagging. It also notes that each returned passage includes an offset for verbatim quote verification.

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

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

The description is front-loaded with the core action, then efficiently expands with examples, use-case, and technical details. Every sentence earns its place; there is no filler, redundancy, or irrelevant information.

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

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

Despite lacking an output schema, the description specifies the return format: 'top-N passages with character offsets and similarity scores.' It also covers input limits, truncation behavior, and the intended pairing with another tool, making the description fully self-contained for an agent.

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

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

With 100% schema coverage, the baseline is a 3. The description enriches two parameters: it explains what kind of text to pass (e.g., SEC 10-K body, article) and provides concrete example queries. The 'limit' parameter receives no extra text, but its schema description is clear, so the incremental value is strong but not full.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates the tool from siblings by explaining it works on text already pulled, and explicitly names ask_pipeworx_grounded with a distinct workflow.

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

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

The description gives an explicit condition: 'Use when the record is too big to cram into the prompt.' It also prescribes a workflow with ask_pipeworx_grounded, effectively contrasting with an alternative approach and giving the agent clear decision 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 annotations, the description discloses important operational behavior: auth requirements, type-specific filter syntax, delivery channel constraints (feed always on, sms requires verified phone with 10/day cap, webhook signing secret returned once and auto-disabled after 10 consecutive failures). This provides significant context that the 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 dense but well-structured: it opens with a clear purpose, then requirements, supported types, and delivery details. Every section adds value without redundancy, and the length is justified by the tool's complexity.

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

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

It covers auth prerequisites, the main subscription types, delivery options with edge cases (phone verification, SMS cap, webhook disable), and return behavior (new subscription id and one-time webhook secret). Given no output schema and high tool complexity, this is thorough — even though two schema-defined types (patent_grant, clinical_trial) are omitted from the main description, the schema fills that gap.

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

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

The schema already covers 100% of parameters with detailed examples, giving a strong baseline. The description adds extra meaning such as 'items:["5.02"] = officer change' for sec_8k and webhook HMAC signing behavior, enriching the parameter semantics 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and notes it returns the new subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

It gives clear context for proactive monitoring and mentions the OAuth prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), implying use for ongoing alerts versus one-time queries. However, it does not explicitly exclude alternatives or name when not to use it, so it falls short of full explicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results come 'from the live catalog of thousands of tools' and are organized by category, which goes beyond the structured annotations. 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?

A single dense paragraph that packs in examples, purpose, return format, and usage guidance. Every sentence contributes value, though the semicolon-heavy structure could be broken into shorter sentences for easier scanning. No filler.

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

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

With only one optional parameter and no output schema, the description fully covers what the tool does, what it returns, the categories offered, and when to use it. It even lists the category names and the meta-tools available, making it complete for onboarding.

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

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

The input schema already describes the only parameter `topic` with 100% coverage, including its enum values and behavior when omitted. The description merely echoes the topic examples ('finance', 'pharma', 'betting') without adding new semantic detail, so the baseline of 3 applies.

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

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

The description clearly states the tool is 'the onboarding entry point' that returns 'category-bucketed example questions' with the 'exact tool + argument shape' for each. It distinguishes itself from sibling tools like ask_pipeworx and entity_profile by positioning itself as the first step to learn what to ask.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also instructs when to call with no arguments vs. passing a topic, and references alternative tools (ask_pipeworx, entity_profile, compare_entities) for comparison.

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 write operation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent. The description adds valuable context beyond that: the row is deactivated (soft delete) not deleted, ownership is enforced, and historical events remain available. This is exactly the kind of behavioral nuance that helps an agent.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence adds critical information. There is no waste or redundancy, 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?

For a simple tool with one parameter, no output schema, and sufficient annotations, the description covers the key behavioral aspects (soft delete, ownership, retention of history) and cross-references recent_alerts. It doesn't mention error handling or edge cases (e.g., non-existent id), but given the simplicity, this is a minor gap.

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

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

The schema already fully describes the id parameter with 100% coverage, including that it's a subscription uuid returned by subscribe. The tool description merely restates 'by id' and adds no further semantic detail, so it provides no added value beyond the schema.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes itself from siblings like subscribe and list_subscriptions by specifying cancellation. The mention of deactivation vs deletion further clarifies the tool's specific purpose.

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

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

The description provides clear context: ownership is enforced, so the tool is only for one's own subscriptions, and it references recent_alerts for historical events after cancellation. While it doesn't explicitly name alternatives, the constraints and cross-reference imply when to use this tool vs others.

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

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

While annotations declare readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context beyond these hints. It explains the two pipelines, the meaning of verdict types (especially distinguishing 'could_not_verify' as 'did not happen' with a verification_error and 'unsupported' as no source found), and notes the inclusion of verbatim evidence with pipeworx:// citations. This is far beyond annotation coverage and clarifies important failure semantics.

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

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

The description is long but information-dense. It front-loads with examples and usage, then details pipelines, verdicts, and error semantics. Each sentence adds functional value, though it could be slightly tightened without losing clarity. The structure flows well from purpose to behavior to return values.

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

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

With no output schema, the description fully compensates by enumerating the verdict types, explaining the actual value with citation, and specifying fields like verification_error. It also covers the two distinct execution paths and what 'unsupported' means. For a tool with this complexity, the description is remarkably complete, leaving little ambiguity about inputs, outputs, or failure modes.

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

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

The schema already describes both parameters with 100% coverage, but the description enriches them further. It explains that tolerance_pct overrides the tolerance implied by claim wording, gives a use case for hallucination detection, and specifies the default behavior (implied by wording, capped at 5). The claim parameter is exemplified with realistic phrases, which aids selection and formatting.

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 natural-language examples and clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It distinguishes the tool from siblings by explicitly describing the two execution paths (SEC EDGAR + XBRL fast path vs grounded pipeline) and stating it 'Replaces 4–6 sequential calls,' which differentiates it from generic query or research tools.

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

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

It gives an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies routing for company-financial vs other claims. However, it does not explicitly name alternative tools or provide 'when-not-to-use' exclusions, though the 'Replaces 4–6 sequential calls' hints at when this is preferable.

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