Arcgis Longview

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

The description adds substantial behavioral context beyond annotations: scoring scale (0-100), free vs. paid model access, need for API key, and return structure per model (score, confidence, signals, raw_response) plus combined view. It also discloses cost implications for Anthropic calls. These details complement the readOnly and idempotent annotations without contradiction.

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

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

The description is compact (4 sentences) and front-loaded with the purpose and score scale. Each sentence contributes: purpose, model selection/cost, return format, and use cases. 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?

Since there is no output schema, the description compensates by clearly stating the return fields (per-model {score, confidence, signals, raw_response} + combined view) and the scoring scale. The tool is moderately complex (4 params, 1 required, optional key), and the description covers purpose, usage, output, and cost, making it complete for effective 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 description coverage is 100%, so baseline is 3. The description adds extra meaning by specifying the default model ('Workers AI Llama-3.3-70b'), clarifying that omitting 'models' yields a free default, and explaining the cost/payment implications of `_apiKey`. These enrich parameter understanding 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 uses a specific verb 'Probe' with a clear resource (one or more LLMs) and an explicit outcome (score visibility 0-100). It also names the default model and optional Anthropic integration, making it distinct from sibling tools like ask_pipeworx which focus on asking questions rather than scoring visibility.

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

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

The description provides clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also gives guidance on model selection and cost ('Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic'). However, it does not explicitly mention when not to use the tool or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds valuable context: routing behavior, argument filling, structured output with pipeworx:// citation URIs, and that it works on every tier as a fast default. This goes beyond the annotations, though it doesn't mention potential limitations or edge cases, preventing a 5.

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

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

The description is long but well-structured: opening directive, domain list, examples, default entry note, and step-up guidance. Every sentence serves a purpose, and the most critical information (preference, what it does) is front-loaded. Slightly verbose due to the extensive domain enumeration and examples, but not wasteful.

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

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

Given the tool's complexity (router to thousands of tools) and lack of an output schema, the description adequately covers return value (structured answer with citation URIs), usage context, and alternatives. It provides enough for an agent to decide when and how to use it, though it could mention potential ambiguity handling or limits, keeping it from a 5.

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

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

Schema coverage is 100% with clear parameter descriptions and aliases. The description adds value by providing numerous real-world examples of valid questions and explaining the natural language input expectation. This enriches the schema's basic 'question' definition, though the schema already covers the core semantics.

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

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

The description clearly states the tool's function: routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citations. It uses specific verbs ('routes', 'fills', 'returns') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making the purpose unambiguous.

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

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

Explicit 'PREFER OVER WEB SEARCH' directive, concrete when-to-use triggers ('what is', 'look up', 'find', etc.), and clear step-up alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). This provides comprehensive usage guidance and exclusions.

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

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

The description discloses that it is an experimental edge with candidate routing improvements enabled live, and that no candidate is currently active, so it currently matches ask_pipeworx exactly. It also clarifies 'Falls back to nothing — this IS a full working router,' which adds context beyond the safe read-only annotations. However, it doesn't discuss rate limits, error behavior, or response format details.

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

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

The description is four sentences, each carrying essential information: what it is, current state, when to use it, and a fallback clarification. It is front-loaded with the core purpose and contains 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?

Given the tool is a beta variant with no output schema, the description provides necessary context by mentioning the 5,529 tools, same arguments, and same response shape as ask_pipeworx. This is sufficient for an agent to understand scope and expected behavior, though it could have elaborated on return format or error handling.

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 covers 100% of parameters, each documented as an alias for 'question'. The description does not add any parameter-specific semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. This is a specific verb-resource combination that distinguishes it from siblings like ask_pipeworx and ask_pipeworx_grounded, which are not mentioned.

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 it exactly like ask_pipeworx when you want the newest routing,' which gives a clear when-to-use condition. It also implies the stable ask_pipeworx is the alternative for non-experimental routing, though it does not explicitly state 'use ask_pipeworx for stable production'.

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

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

Despite annotations already marking this as read-only and idempotent, the description adds substantial behavioral detail: how it avoids hallucination by using only tool results, that it incurs an extra LLM call, and the exact refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). This goes well beyond the annotations and does not contradict them.

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

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

The description is dense but every sentence contributes: purpose, mechanism, output/refusal contract, usage context, and cost trade-off. It front-loads the most critical info (hallucination-resistant, high-stakes) and structures the refusal reasons compactly. No wasted words.

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

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

The description fully specifies return values despite lacking an output schema, including the exact fields for success and the refusal_reason enum. It also covers routing behavior, cost implications, and when to choose alternative tools, making the description 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?

The input schema fully covers all six parameters (question and five aliases) with 100% description coverage, so the description adds no parameter-level semantics. The baseline of 3 is appropriate because the schema already documents the parameters adequately and the description does not need to compensate.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that routes to tools and extracts grounded answers, explicitly contrasting it with ask_pipeworx and naming the key distinction (evidence, refusal behavior). It states the specific output structure on success and failure, making the tool's function unmistakable.

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

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

It provides explicit when-to-use guidance: for high-stakes reads where answers will be quoted, cited, or acted on. It also gives a clear when-not-to-use instruction by stating it costs an extra LLM call compared to ask_pipeworx and recommending ask_pipeworx for casual lookups, naming the alternative directly.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds substantial behavioral detail: resolver contract with confidence levels and alternatives, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread-market warnings, news fallback fields, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded purpose. Every sentence serves a purpose, but it is dense and might be overwhelming for a quick scan. A 4 balances thoroughness with structure.

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

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

With no output schema, the description carries full burden for return-value interpretation. It covers result.market, result.analysis, result.evidence, resolver contract, parent_event extractor, news fallback fields, safety statuses, and resolution-rule risk. This is remarkably complete for a complex tool, enabling correct invocation and result 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?

Input schema covers 100% of parameters with clear descriptions (market formats, depth values, include_raw default/size impact). The description reinforces these with examples but adds little beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 states a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_arbitrage or validate_claim by focusing on a single bet with data fan-out and a market-vs-model comparison. The 'Use for' line also gives concrete example queries.

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 'Use for "should I bet on X"...' and provides classifier categories and fan-out examples, giving clear context on when this tool fits. However, it does not explicitly mention when NOT to use it or name alternatives (e.g., polymarket_arbitrage for cross-market opportunities), so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses specific data pulled for each type (10-K financials for companies, FAERS/FDA/trial counts for drugs), handles off-calendar fiscal years, sorts by primary metric, and mentions citation URIs in returns. This provides 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 front-loaded with the core purpose and trigger phrases, then succinctly covers type-specific details, sorting, output, and efficiency. Every sentence earns its place without unnecessary fluff, given the tool's complexity.

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

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

With no output schema, the description still explains return values (paired data + citation URIs). It covers data sources, entity types, sorting behavior, and parallels the schema's constraints (2–5 items). The tool is fully comprehensible without needing to consult other resources.

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

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

Although schema coverage is 100%, the description adds substantial meaning: type='company' vs 'drug' behavior, examples of values (['AAPL','MSFT'], ['ozempic','mounjaro']), and details on what data is pulled for each type. This goes far beyond the schema's basic enum and array descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like 'compare X and Y' and 'head to head'. It distinguishes itself from single-entity lookups by emphasizing 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

Provides explicit guidance on when to use this tool: when comparing entities, it should be preferred over sequential single-pack lookups. It also gives concrete examples of user intents and notes it replaces 8–15 sequential lookups, reinforcing the use case.

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 reveals important behaviors: account requirements, not open-web, parallel routing, gaps[] that are never invented, hop field, citation_uri only when fetchable, contradictions[] for standard/thorough, semantic excerpting, and reasonable latency expectations. This adds substantial context beyond structured annotations.

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

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

The description is a long, dense paragraph that covers many essential points but lacks clear structure or front-loading. It starts with account requirements rather than the core function, and while every sentence carries information, a bulleted or sectioned format would improve readability given the tool's complexity.

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

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

With no output schema, the description thoroughly explains what the tool returns: a findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field, and semantic excerpts. It also covers latency and depth semantics, making the tool's behavior fully comprehensible without needing additional documentation.

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 documentation is complete (100% coverage), but the description enriches the depth parameter with concrete behavior: quick=3, standard=5 (default with gap recovery + contradictions), thorough=8 (paid with iterative hop + contradictions). It clarifies that 'question' can be broad/multi-part, which is not explicit in the schema.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, explicitly distinguishing it from open-web search and sibling tools. It also specifies the key resource (structured data sources) and the action (decomposes and routes to tools in parallel).

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also mentions account tier requirements and the depth options, making it clear when to choose this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by explaining the return format (top-N tools with names, descriptions, and full input schemas) and that results are directly callable, going beyond what annotations provide.

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

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

The description is well-structured and front-loaded: it states the core purpose in the first sentence, then covers usage scenarios, supported domains, output details, and priority guidance in subsequent sentences. Every sentence adds distinct value with 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?

The description is complete for this tool's complexity. It explains what the tool does, when to use it, what it returns (including that schemas are included with examples), and how to prioritize its use. With a simple input schema and no output schema, this fully covers the context an agent needs.

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 the query parameter's purpose with domain examples, but the schema already describes it thoroughly. No significant additional parameter semantics are added.

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 'Find tools by describing the data or task,' clearly identifying the tool's verb and resource. It also lists specific domains and explains that it returns relevant tool schemas, which distinguishes it from data-query tools like search_datasets.

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 advises 'Call this FIRST when you have many tools available.' This provides clear when-to-use guidance, though it does not explicitly name alternatives or state when not to use the 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?

With annotations declaring readOnly/openWorld/idempotent, the description adds behavioral context such as fanning out across SEC EDGAR, XBRL, USPTO, news, and GLEIF in one parallel call, plus the patent API sunset soft-fail and GDELT→GNews fallback. It accurately describes the return structure and limitations without contradicting the annotations.

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

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

The description is lengthy but well-structured with example queries, purpose, return fields, and parameter notes in a logical order. While it contains some redundancy (e.g., repeating the schema's parameter notes), the density is necessary to convey the tool's complexity and multi-source behavior.

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

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

Given there is no output schema, the description thoroughly enumerates all return components: cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions with fallback, and LEI. It also explains the patents soft-fail and the name resolution prerequisite, making the tool's behavior fully understandable.

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

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

Schema description coverage is 100%, and the description's parameter guidance ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') essentially duplicates the schema's existing descriptions. No additional parameter semantics are provided beyond what the schema already contains, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call', with multiple concrete example queries. It distinguishes itself from sibling tools by explicitly preferring this over chaining single-pack lookups for holistic views. The verb+resource is specific and unambiguous.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a direct alternative: 'names not supported (use resolve_entity first if you only have a name).' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint and idempotentHint. The description adds context about clearing sensitive data but doesn't disclose additional behavioral details like irreversibility or behavior on missing keys; it doesn't contradict annotations.

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

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

Two sentences are front-loaded with the core action, then usage guidance; every word earns its place.

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

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

For a one-parameter delete tool with strong annotations and no output schema, the description adequately covers core function, usage timing, and relation to sibling tools. Minor gap: no mention of non-existent key behavior, but idempotentHint covers that implicitly.

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% for the single key parameter, and the description merely says 'by key' without adding format or lifecycle details, so it adds no extra 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 opens with 'Delete a previously stored memory by key,' using a specific verb and resource that clearly distinguishes it from sibling tools like remember and recall.

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 use cases (stale context, task done, sensitive data) and suggests pairing with remember and recall, but doesn't explicitly state when not to use it.

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 destructive=false, so the description adds value beyond that by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also discloses the output format: 'a single text blob ready to drop at site-root/llms.txt.'

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

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

Two sentences, front-loaded with the core action. No redundant words; the first sentence states purpose and the second gives process and use cases.

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

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

For a tool with 2 params, rich annotations, and no output schema, the description covers purpose, process, output format, and use cases. It is fully self-contained and sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100% (both url and max_links have descriptions). The description doesn't add additional parameter-specific meaning beyond what the schema provides, so 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 'Generate a production-ready llms.txt file for any URL', specifying the verb (generate), resource (llms.txt), and scope (any URL). It also distinguishes from siblings by mentioning the use case of 'auditing how an AI crawler would see a competitor', which overlaps with scanning tools.

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

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

The description 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'. While it doesn't name alternatives, it gives clear context for when to use the 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=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what data the tool retrieves (fields, geometry, count, capabilities), which is useful behavioral context beyond the annotations. It does not discuss potential errors or external network dependencies, but the core behavior is transparent.

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

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

The description is a single, front-loaded sentence that includes all necessary information without redundancy. Every phrase earns its place, and the structure is perfectly concise.

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

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

Given the low complexity (one parameter), rich annotations, and absence of an output schema, the description is complete enough. It clearly states the return content and implicitly scopes the tool to schema retrieval, which covers the essential information an agent needs.

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

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

The input schema has 100% coverage with a clear description of the url parameter. The description's mention of 'by url' adds no new semantic meaning beyond the schema. The list of returned items gives some context but does not elaborate on parameter format or constraints, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource: an ArcGIS Feature/Map Service layer's schema. It enumerates the exact information returned (fields, geometry type, record count, capabilities), which distinguishes it from sibling tools like query_layer that work with 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 implies usage (when you need schema details), but it does not explicitly mention alternatives or when not to use this tool. While the sibling context suggests query_layer for data queries, the description itself offers no such guidance, leaving it to the agent to infer.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the description is consistent. It adds context that it returns only active subscriptions by default, and specifies the return fields, which helps the agent understand the tool's scope and behavior beyond the 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?

Three sentences, front-loaded with the purpose, then return fields, then use case. Efficient and no redundant 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?

For a simple list tool with strong annotations and full schema coverage, the description covers the essential information: what it returns, default filtering, and when to use it. It could mention pagination or limits, but that's not critical for this simple operation.

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

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

Schema coverage is 100% for the single parameter include_inactive, so the baseline is 3. The description doesn't add further meaning to the parameter, but it references 'active' which aligns with the default behavior.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from siblings by mentioning it returns subscription details and can be used to find an id to cancel.

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

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

Explicitly states when to use: to review what you're monitoring before adding more or to find an id to cancel. This clearly separates it from subscribe/unsubscribe tools.

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

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

The description adds significant behavioral context beyond annotations: rate-limited to 5 per day, returns a claim_token without an account, is free and doesn't count against quota, and the team reads digests daily. These details are not available from annotations and directly inform agent decision-making.

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

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

The description is long but well-structured and front-loaded with the core purpose. Every sentence carries useful information, though it could be slightly tightened by moving some operational details into a more scannable format. Still, it avoids fluff and remains readable.

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 thoroughly covers the behavior: how to file, what the token means, how to check resolution, rate limits, and exclusions. It leaves no major gaps for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for the claim_token parameter (how to reuse it to check status) and clarifies that feedback should be described in terms of Pipeworx tools/packs, which helps with the 'context' and 'message' parameters.

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

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

The description clearly states the purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team') and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than queries.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and when-not-to-use ('if the tool came from a different MCP server... file it with that server instead'). Also advises on what not to include (don't paste the end-user's prompt). This is exemplary usage guidance.

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

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

Annotations already mark it read-only/idempotent/open-world. The description adds valuable behavior: data derived from CF analytics-engine, no PII, aggregation structure (pack, tool, count), and caching freshness (5min-1h depending on window). This exceeds the minimum and gives agents appropriate expectations.

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

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

Well-structured: a one-sentence summary, three concrete use cases, and a compact technical note. No filler or redundancy; each clause adds 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?

For a single-optional-param read-only trend query, the description covers purpose, use cases, data source, privacy, caching, and return contents. No output schema exists, so the return description ('top tools, top packs, total call volume') is sufficient.

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

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

There is one optional parameter (window) with a complete schema description and enum. The tool description mentions the window options but does not add new semantics beyond schema. The schema itself explains short vs long window trade-offs, so a 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 its function: showing what other AI agents are calling on Pipeworx and returning top tools/packs/call volume over a window. This differentiates it from sibling tools like discover_tools or recent_alerts by focusing on aggregate agent 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 useful-for scenarios (discovering hot data sources, confirming canonical tool, checking alignment) but does not name alternative tools or state when not to use it. Clear context and intended use cases warrant 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 readOnlyHint and idempotentHint, but the description adds rich behavioral detail: threshold >3pp for signals, Jaccard similarity ≥0.30 for semantic pairing, placeholder filtering (20% threshold), and the fill check against live CLOB depth. This goes well beyond the annotations and provides critical context for interpreting results.

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

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

While long, the description is densely informative and well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value—no redundancy or filler. Important details are front-loaded, and the formatting makes complex behavior easy to scan.

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 and only two optional parameters, the description covers all necessary context: response structure, thresholds, failure modes, and caveats. It also references sibling tools to direct users for related tasks, making it effectively self-contained for an AI 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 descriptions cover the basic purpose of each parameter, but the description adds substantial semantics: event mode walks child markets and checks ordering plus partition_check, while topic mode searches related events and flattens markets. It also provides concrete examples of valid inputs (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal').

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and a default trending scan, making it specific and distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: event for a specific market, topic for cross-event scanning, and no args for a trending scan. It also references an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk') and warns against trading when realizable edge is non-positive.

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 readOnly/openWorld/idempotent annotations, disclosing caching behavior ('Cached 1h at the KV level keyed on all knobs.'), response structure with diagnostics for empty segments, and nuanced caveats (e.g., the 24h-move warning when recent price movement already exceeds the edge). It also explains why partition_overround opportunities carry a parent-level kelly_fraction_half=0, which is not obvious from annotations alone.

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

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

The description is long and dense, but every sentence carries substantive information about model families, response segments, filters, and diagnostics. It is structured with clear uppercase headers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core use case. It is not as tight as a two-sentence ideal, but 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?

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the return structure (by_segment, fed_candidates, _diagnostics), how to interpret empty segments (funnel counters show why), and even the reasoning behind unreliable Fed signals. The absence of an output schema is compensated by a thorough prose description of what callers will receive.

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

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

The input schema already provides 100% parameter coverage with clear descriptions, so the baseline is 3. The description adds value by explaining the rationale behind knobs: 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable', and it clarifies a subtle interaction—min_kelly never filters partition arbs because they use per-leg Kelly instead. This extra context helps agents choose values correctly beyond what the schema states.

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

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

The description states a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself from siblings by enumerating the five model families and the built-for use case ('what should I bet on today'), making clear what kind of edge detection it performs that other tools might not.

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 the tool: when agents want a curated list of opportunities without paging through hundreds of markets. It gives concrete knob-setting examples (e.g., setting min_liquidity to 5000 to drop thin-book opportunities) and even explains when the Fed signal is unreliable. However, it does not explicitly name alternatives or state when not to use this tool versus a sibling like polymarket_arbitrage.

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 (readOnlyHint, idempotentHint, etc.) by disclosing data limitations: 60-day snapshot TTL, availability starting from when snapshotting was enabled, gaps meaning no scan, and decay computed from daily closes not intraday. It also explains the meaning of negative edge values. This is rich behavioral context that helps the agent anticipate edge cases.

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

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

The description is structured with clear labels (Args, RESPONSE, LIMITS) and front-loads the core question. Every sentence adds value: it defines the tool's purpose, parameter semantics, response format, and data limitations without fluff. The use of capitalization for response fields aids parsing.

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 structure (tracked, expired, snapshot_dates) and provides interpretation guidance ('median lifespan is your competition clock'). It also covers history depth and computation method. Given the tool's complexity, this is complete and 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% and the description reinforces both parameters with defaults and interpretation ('days' lookback with max, 'window' snapshot family). It adds the concept of 'snapshot family' and clarifies how negative edge_pp_net maps to trade direction. While the baseline for high schema coverage is 3, the description adds enough nuance to warrant a 4.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly states the question it answers ('how long has this edge existed and is it shrinking?') and contrasts fresh vs. old edges, which clearly distinguishes it from siblings like polymarket_edges that likely show current edges.

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

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

The description provides clear context for when to use this tool: it is for assessing edge persistence and decay, with the example that a 3-week-old wide edge is a different trade than a fresh one. It also explains what expired opportunities and median lifespan reveal. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

The description discloses rich behavioral details: walking the order book, interpreting size_usd in both modes, returning specific metrics, and warning about partial fills converting arbs into unhedged directional risk. It adds significant context beyond the annotations and does not contradict them.

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

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

The description is long but well-structured with clear mode headings (SINGLE-MARKET, BASKET) and a final usage directive. Every sentence contributes necessary information, and the content is appropriately front-loaded with the core purpose.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly enumerates return fields for both modes and highlights risk scenarios like thin books and forced directional risk. It leaves no major gaps for an agent to misuse the tool.

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

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

Although schema coverage is 100%, the description adds meaningful semantic value: clarifies side defaults, the dual interpretation of size_usd (spend vs proceeds vs settlement notional), and the mutual exclusivity of market and event. This goes well beyond the schema descriptions.

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

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

The description states a specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges and describing its unique role in execution risk assessment.

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 provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also differentiates single-market and basket modes and explains the required input combinations.

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

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

Beyond the readOnly/idempotent annotations, the description discloses warning behavior (compatibility_warning trigger conditions), semantic validity (temporal_alignment.aligned:false meaning), and dropped-comparison counters (skipped_cross_type/subtype). This substantially exceeds annotation-provided safety signals.

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 (~280 words) but structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. Slightly verbose; the repeated 'pre-mapped ≠ tradeable' warning could be trimmed.

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

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

Without an output schema, the description still documents the response shape (leg-by-leg raw probabilities, spread.pp, warning fields) and two meaning-failure conditions. Given the tool's complexity and zero required params, coverage is near-comprehensive.

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 the mode-level semantics — how topic relates to the two override parameters — and clarifies that all parameters are optional, which the schema leaves implicit.

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 specific resource: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from sibling polymarket-only tools (polymarket_arbitrage, polymarket_edges) by the cross-venue scope, and states the two operating modes.

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?

Two explicit modes are documented: topic shortcuts for pre-mapped events and explicit ticker+slug for custom pairings, giving clear when-to-use guidance. It also states a when-not caveat ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'), though it never names alternative sibling tools explicitly.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds that it returns attribute rows and geometry, and hints at SQL-like filtering semantics. It does not disclose error handling, but the schema covers limits and defaults, so the added context is valuable.

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

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

Two sentences, front-loaded with the core action, and no unnecessary repetition. The sampling tip is useful and directly actionable, making every sentence earn its place.

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

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

For a read-only query tool with full schema coverage and clear annotations, the description covers what it returns, how to obtain the URL, and a usage pattern. It doesn't address the relationship to search_within for spatial queries, but the core functionality is well-specified and complete enough for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning: 'SQL-like' clarifies the where clause, 'comma-separated' clarifies out_fields format, and the sampling idiom provides real-world usage 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 uses the specific verb 'Query' with the resource 'ArcGIS Feature Service / Map Service layer', and references the source 'from search_datasets', making the tool's purpose unmistakable. It also lists key parameters, clearly distinguishing it from metadata-focused siblings like layer_info.

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

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

It implies usage by referencing search_datasets for the URL and provides a concrete sampling tip (where='1=1' + out_fields='*'), giving clear context. It does not explicitly exclude alternatives like search_within for spatial queries, but the guidance is sufficient for most cases.

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 covered. The description adds valuable behavioral context about scoping ('Scoped to your identifier') and the dual-mode behavior (fetch single key vs list all), which annotations do not provide.

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

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

The description is three tightly written sentences: the first defines the function, the second frames when to use it, and the third covers scoping and sibling pairing. No filler or redundant phrasing—every sentence earns its place.

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

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

For a tool with one optional parameter, strong annotations, and no output schema, the description fully covers purpose, usage, scope, and relationship to related tools. It answers the likely questions an agent would have without needing additional detail.

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

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

Schema description coverage is 100% with the key property already described as 'Memory key to retrieve (omit to list all keys)'. The description mirrors this and adds examples of key values, but it does not add any new semantic detail beyond the schema, so it sits at the baseline.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys when key is omitted. It gives concrete examples (target ticker, address, research notes) and distinguishes itself from siblings like remember 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?

The description explicitly says 'Use to look up context the agent stored earlier' and provides alternative guidance by naming remember and forget in 'Pair with remember to save, forget to delete.' This makes the when-to-use vs alternatives crystal 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?

There is a direct contradiction with annotations. The annotations declare readOnlyHint=true and destructiveHint=false, which imply no persistent state changes. However, the description says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' indicating a mutation of persisted state. This contradicts the read-only annotation, so the score is 1 per the contradiction rule.

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: it starts with the core purpose, then return contents, filtering options, mark_read behavior, and alternative access. Every sentence contributes value, with no redundancy or filler. It is appropriately sized for the tool's complexity.

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

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

There is no output schema, but the description explains the return payload (source, citation_uri, raw event payload), covers the key filtering and state-change behaviors, notes that polling is safe, and points to an alternative GET endpoint. This provides comprehensive context for an agent to use the tool effectively, even without explicit return 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%, so the baseline is 3. The description adds meaningful usage semantics beyond the schema: it gives a concrete example for type ('sec_8k'), specifies since as an ISO timestamp, and explains the behavioral effect of mark_read on subsequent calls. This enriches parameter understanding beyond field descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' and details the return contents (source, citation_uri, raw event payload). This distinguishes it from siblings like list_subscriptions, which manage subscriptions, and recent_changes, which likely handles different data. The verb 'Pull' and resource 'alerts' are specific.

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: it is for reading the persisted alert feed, filtering by type and since, and using mark_read to control read state. It also mentions polling is fine and points to an alternative HTTP endpoint. However, it does not explicitly exclude alternatives like recent_changes or list_subscriptions, so it lacks explicit when-not-to-use guidance.

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

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

The description goes far beyond annotations by disclosing the fan-out architecture, the GDELT→GNews fallback trigger (rate-limited or 5xx), and the USPTO PatentsView API sunset soft-fail. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds meaningful external dependencies and failure modes.

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

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

The description is dense but every sentence provides value: user-question examples, source list, fallback behavior, parameter explanation, and return structure. No fluff or redundancy. The structure front-loads the purpose and then provides necessary operational details.

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

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

For a tool with multiple sources, fallbacks, and date handling, the description covers all critical aspects: source behavior, failure modes, input formats, and output structure (changes[], total_changes, citation URIs). No output schema exists, but the description compensates by describing the return payload. It also points to the alternative tool, making it contextualized within the tool ecosystem.

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

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

Schema coverage is 100%, and each parameter has a descriptive explanation. The description adds no new parameter semantics beyond what's in the schema, but it reinforces the `since` format with examples. Baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states it is a change feed for a company in the last N days/weeks/months, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It uses specific verbs like 'fans out' and 'returns structured changes[]', and differentiates from the sibling tool entity_profile.

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

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

Explicitly states when to use this tool versus entity_profile: 'Use entity_profile instead when you want the static profile... regardless of window.' It also provides usage examples ('What's new with X') and mentions the fallback behavior, giving clear context for when this is the right 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 cover read-only, idempotent, destructive hints, and the description adds behavioral context: key-value scoping by identifier, persistence differences between authenticated and anonymous users (24-hour retention), and session-crossing capability. It does not contradict annotations, though it could detail overwrite behavior, which is implied by 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 four sentences, each serving a distinct purpose: main action, usage context, storage/retention details, and pairing with related tools. It is front-loaded with the core purpose and contains 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?

For a simple write tool with no output schema, the description covers all essential aspects: what, when, how (key-value), scoping, persistence, and complementary tools. It provides sufficient context for an agent to use it correctly without any gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions key-value pair but does not add significant parameter-specific meaning beyond the schema's examples and descriptions. It reinforces that 'value' is free text, matching 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 saves data for later reuse with specific verb 'Save' and resource 'data'. It distinguishes from siblings by explicitly pairing with recall for retrieval and forget for deletion.

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

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

It provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It names alternatives (recall, forget) and explains the pairing, making it clear 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?

Beyond the readOnly/idempotent annotations, the description reveals key behavioral traits: graceful degradation ('LEI/FIGI enrichment degrades gracefully'), explicit unresolved reporting ('an identifier that could NOT be resolved is stated explicitly under `unresolved` rather than omitted'), and internal endpooint cascading. It also labels identifiers with their source, adding context annotations alone do not capture.

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 purpose and usage guidance; the many example queries are all illustrative of the supported inputs. The company-type expansion is dense but meaningful, and every sentence contributes value; it is slightly long but not wasteful.

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

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

With no output schema, the description does a thorough job of describing return values: for company it lists CIK, ticker, company_name, LEI, FIGI, and ownership; for drug it lists RxCUI and citation. It also explains unresolved handling, graceful degradation, and the internal cascading, leaving no major gaps for an agent to invoke it correctly.

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

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

Both parameters are already fully described in the schema with 100% coverage, so the baseline is 3. The description mostly restates what the schema says (ticker, CIK, name; brand or generic) and adds more information about output behavior than about the parameters themselves. The added clarity about 'user-spoken NAME' is marginal.

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

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

The description opens with concrete user queries and states a clear, specific purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes itself from siblings by instructing 'Use FIRST whenever you have a name but need an ID' and by itemizing supported entity types.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID' and explains that the tool replaces 2-3 manual lookups. It does not explicitly name alternative tools for when an ID is already known, but the use case is clearly scoped.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by disclosing that the tool probes each entity with ai_visibility_check, ranks by score, and returns a structured result with score, confidence, and signal density. This adds useful 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 only two sentences. The first sentence states the action and method, the second provides a use case and output format. Every sentence earns its place with no redundancy or fluff.

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

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

The description covers purpose, method (probes ai_visibility_check), output format (ranked list with score/confidence/signal density), and a concrete use case. Although there is no output schema, the description supplies return details. Given the moderate complexity and well-documented parameters, it is nearly complete.

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

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

The schema provides 100% coverage for all four parameters with descriptive text. The description does not add meaningful parameter semantics beyond what is already in the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Compare AI visibility across multiple entities side-by-side', a specific verb+resource that clearly states the tool's function. It distinguishes itself from sibling ai_visibility_check by explicitly mentioning multi-entity comparison and ranking, making the purpose unambiguous.

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

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

The description provides clear context with 'Useful for competitive AI-marketing audits' and an illustrative query. It implies this tool is for multi-entity comparison vs. single-entity checks, but does not explicitly name alternatives or list exclusions, so it stops short of a 5.

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

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

Beyond readOnly/idempotent annotations, it discloses partial failure degradation, the 5-30s first-measurement delay, and the sources_failed field. This is valuable operational context.

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

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

The description is slightly long but every sentence adds value. It's front-loaded with the core purpose and then covers use cases, return structure, and failure modes in a logical flow.

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 composite tool with no output schema, the description enumerates all return fields (summary block fields, advisories, links, alternatives) and explains edge cases (partial failures, ecosystem limits). This is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the description adds little beyond the schema. It does mention scoped packages and version default, but these are already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific composite check, naming deps.dev and bundlephobia and clearly stating it evaluates npm packages. This distinctively separates it from sibling tools, which focus on AI visibility or market edges.

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

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

It explicitly states when to use ('is X safe / popular / small', 'what does adding lodash cost me') and gives an exclusion: non-NPM ecosystems should go to deps.dev:version directly.

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

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

Annotations already declare the tool safe (readOnly, openWorld, idempotent). The description adds useful behavior context: returns each dataset's name, summary, record_count, owner/org, and the Feature Service url, plus a usage workflow. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose, includes examples and return details, and provides actionable follow-up. 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?

Given no output schema, the description fully discloses return fields and usage flow, and includes domain context. It covers all key aspects an agent needs to select and invoke the tool correctly.

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

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

The schema has 100% coverage for all 3 parameters with clear descriptions, so the baseline is 3. The description doesn't add new parameter semantics beyond 'keyword' which aligns with the query param, but it also doesn't need to.

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 resource ('City of Longview GIS open geospatial datasets') with examples of content, and distinguishes itself from sibling tools like query_layer and layer_info by explicitly stating it returns the Feature Service url for those tools to use.

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

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

It clearly states the tool is for searching datasets and provides follow-up guidance ('pass that url to query_layer / layer_info'), indicating when to use this tool vs. alternatives. It doesn't explicitly say when not to use it, but the context is strong.

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

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

The description discloses the embedding model (BGE-base-en), algorithm (cosine over 500-char overlapping windows), and the 200K character limit with truncation flagging. These details go well beyond the readOnly/openWorld/idempotent annotations, giving the agent a clear picture of operational constraints.

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 purpose, follows with conditional usage, and ends with technical specifics. Every sentence serves a distinct function—purpose, use case, pairing, and implementation—with 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?

Despite lacking an output schema, the description explains the return format (top-N passages with character offsets and similarity scores) and the verification benefit. It covers inputs, limits, behavior, and use case, making it fully self-contained for a complex semantic search tool.

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

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

The schema already covers all three parameters at 100% coverage, so baseline is 3. The description earns a 4 by adding concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying that 'text' is the already-fetched record, which enriches the schema's bare definitions.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by emphasizing the input is already-pulled text (e.g., SEC 10-K, article) and explicitly contrasts with grounding over the whole document.

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 provided: 'Use when the record is too big to cram into the prompt' and directly names a complementary tool ('Pairs with ask_pipeworx_grounded'). This tells the agent exactly when to choose this tool versus alternatives.

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

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

Beyond annotations (readOnly=false, idempotent=true), the description adds key behaviors: authentication requirement, feed always-on with pull methods, SMS verification and 10/day cap, and that anonymous/BYO cannot persist. It does not mention webhook delivery or error cases, but annotations already cover the write/idempotent nature.

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?

Every sentence adds value; front-loaded with core purpose, then auth, types, and delivery. Dense but not redundant or bloated, appropriately sized for a tool with nested objects and multiple enums.

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?

Rich coverage of return value (subscription id), auth needs, types, and delivery options. However, the prose omits webhook delivery (covered only in schema) and does not mention error/failure behavior. Given no output schema, the return value is explained, and schema compensates for webhook details.

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

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

Even with 100% schema coverage, the description adds type-specific examples (e.g., items:['5.02'] = officer change, params:{topic:'fed'}) that clarify parameter meaning beyond the schema's terse descriptions. Delivery channel semantics are also explained (verified phone, 10/day cap).

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. The description differentiates itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation and explicitly describing supported subscription types and delivery channels.

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

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

Provides clear context: prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist), supported types with examples, and delivery channel options. However, it does not explicitly name alternative tools (e.g., list_subscriptions, unsubscribe) or state when not to use this tool beyond the auth restriction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context beyond that: it returns category-bucketed example questions, includes the exact tool and argument shape for each, and is drawn from a live catalog. It also clarifies that calling with no arguments returns the full spread, which is a behavior not evident from annotations alone.

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 rich with examples and usage guidance. It front-loads the most important query phrases, then explains the return format and call variations. Every sentence contributes to understanding the tool's value and use, though it could be tightened slightly without losing substance.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument mappings), how it behaves with and without the optional topic parameter, and when to use it. This is highly complete for an onboarding/discovery tool, covering purpose, usage, and behavior comprehensively.

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

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

The schema already provides 100% coverage for the single `topic` parameter with a description and explicit enumeration of valid values. The description only restates the optional nature and gives a few examples, adding minimal semantic value beyond the schema. Baseline 3 applies because schema coverage is complete.

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

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

The description clearly states the tool's purpose: it's the onboarding entry point for agents wanting to know what questions to ask Pipeworx. It enumerates example query types and explicitly distinguishes itself from related tools by noting it provides exact tool + argument shapes, making it distinct from siblings 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?

The description gives explicit use cases: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'. It also explains the optional `topic` argument for focused queries. However, it doesn't explicitly state when NOT to use this tool (e.g., when you already know the exact tool to call), so it misses a clear exclusionary 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 cover idempotency and non-destructiveness, but the description adds crucial behavioral context: ownership enforcement and the deactivation (not deletion) effect, which impacts data history. This directly supplements the annotations without contradicting them, giving the agent a complete picture of side effects.

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

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

The description is two sentences, front-loaded with the primary action. The second sentence adds two essential behavioral caveats. No filler or redundant information; every sentence earns its place.

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

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

For a simple one-parameter tool with comprehensive annotations and no output schema, this description is fully adequate. It covers the action, ownership rule, and side effects. The absence of return-value details is acceptable given the tool's simplicity and the annotations' coverage.

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

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

The input schema has 100% coverage for the single parameter 'id', describing it as a UUID returned by subscribe. The description does not add any additional parameter meaning beyond what the schema provides, thus scoring at the baseline for high schema coverage.

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

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

The description clearly states the tool's action: 'Cancel a subscription by id.' This is a specific verb+resource pairing that distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. No ambiguity about what operation is performed.

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 on when to use the tool by explaining the ownership constraint ('you can only cancel your own subscriptions') and the deactivation behavior ('the row is deactivated (not deleted)'). This implicitly guides the user that this tool is appropriate when they want to preserve historical alerts while stopping future ones. However, it does not explicitly name alternative tools or exclusion scenarios, so it falls short of a 5.

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

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

Goes far beyond annotations by explaining the tool's two-path behavior (SEC EDGAR vs grounded pipeline), the exact meaning of each verdict, and the error semantics of 'could_not_verify'. The description also clarifies that 'unsupported' indicates lack of coverage. These behavioral details are not present in the annotations and are crucial for correct interpretation.

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 verbose but justified given the tool's complexity. It is front-loaded with trigger phrases, then covers routing, return values, and error semantics. While slightly long, each sentence contributes value; the 'IMPORTANT for callers' section is a deliberate and useful structural addition.

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?

Provides a complete operational picture: input examples, output verdicts and reasoning, source routing, error handling, and caveats. Even without an output schema, the description fully informs the agent about what to expect and how to interpret results, making it sufficient for correct invocation and response handling.

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 description adds significant meaning beyond the schema: it explains that tolerance_pct overrides the implied tolerance, that 1–2 is suitable for hallucination detection, and that the default is capped at 5. This supplements the schema descriptions, which only list basic usage, thereby enriching the agent's understanding of parameter behavior.

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 verifies natural-language factual claims against authoritative sources, with specific trigger phrases and examples. It distinguishes itself from sibling tools by mentioning its role as a single-call replacement for 4–6 sequential steps, making its purpose specific and unambiguous.

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

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

Explicitly instructs when to use: whenever checking whether a user's statement is factually correct. Differentiates between company-financial claims (fast path) and other claims (grounded pipeline), giving clear routing context. Also notes that 'could_not_verify' is not a verdict, providing important caller guidance.

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