Arcgis Novi

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds meaningful beyond-annotation context: default model is free, Anthropic requires a BYO key with direct cost to the user, and it discloses the full per-model response shape (score, confidence, signals, raw_response) plus a combined view. No contradictions; the only missing piece is rate limits or error semantics, but the key context is covered.

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 core action and scoring, then default behavior/cost, then return format and use cases. Every sentence earns its place; no fluff or repetition of schema details.

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

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

Despite no output schema, the description explicitly enumerates the return structure (per-model fields + combined view) and covers the main behavioral aspects (default model, optional Anthropic key, cost implication). For a read-only probe tool with 4 params, this is sufficiently complete for an agent to select and invoke it confidently.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: "Default model is Workers AI Llama-3.3-70b (free); pass `_apiKey` to also probe Anthropic — you pay Anthropic directly" clarifies the relationship between models and _apiKey beyond the schema, and it explains likely values for models (workers-ai/anthropic) without being redundant.

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

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

The description opens with a specific verb+resource: "Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model." It clearly distinguishes itself from siblings like scan_competitor_ai_presence by focusing on direct multi-model probing with a quantifiable score, default model, and Anthropic key option.

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 states clear use cases ("AI-marketing audits, pre-launch brand checks, competitive monitoring") and mentions default vs optional Anthropic probing. It does not explicitly name alternatives or exclusion conditions, but the context makes when-to-use apparent given the sibling tool list.

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 (read-only, idempotent, non-destructive). The description adds valuable behavioral context by explaining the routing mechanism (one of 5,462 tools), speed ('one fast call'), tier availability, and that it returns structured answers with citation URIs. It doesn't contradict annotations but doesn't detail potential failure modes or latency.

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 quite long (~200 words) but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and includes examples and alternatives. While every sentence adds some value, it could be tightened without losing meaning. The structure is logical but borderline verbose.

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

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

There is no output schema, so the description must explain return behavior—it does, mentioning structured answers and pipeworx:// citation URIs. It covers the breadth of supported domains, example queries, and sibling escalation. It lacks information on error handling or limitations, but for a general-purpose entry point it is sufficiently complete.

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

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

The input schema covers all parameters with descriptions and aliases (question, q, text, input, query, prompt). Since coverage is 100%, the schema does the heavy lifting. The description adds examples and clarifies that the question is in natural language, but this duplicates what the schema already 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 clearly identifies this as a general-purpose factual question router, explicitly naming the resources it covers (SEC filings, FDA drug data, FRED/BLS, etc.) and stating that it returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the tool's specific role unmistakable.

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

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

Explicit guidance is given: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with concrete examples of when to use it. It also specifies when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). This provides clear decision criteria for the agent.

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

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

Annotations already declare read-only, non-destructive, idempotent, open-world safety. The description adds valuable context beyond annotations: the experimental nature, that candidate routing improvements are enabled live, and that no candidate is currently active. It clarifies that the tool is a full working router with no fallback, which helps set expectations.

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

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

The description is dense but well-organized, with four sentences covering purpose, state, usage, and fallback. It includes specific details (e.g., 5,462 tools, date of last retirement) that contribute to understanding. Slightly long but 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?

Given the tool is a complex universal router with no output schema, the description effectively conveys its relationship to ask_pipeworx, current experimental state, and usage intent. It mentions the same response shape but doesn't detail what that shape is, which would require referencing ask_pipeworx documentation. Overall, sufficient for selection and invocation.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no additional parameter detail beyond saying 'same arguments' as ask_pipeworx, so the schema fully handles parameter semantics. 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 states a specific verb-resource pair ('Ask Pipeworx Beta') and clearly identifies it as a beta version of the universal router, explicitly noting the same 5,462 tools, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by highlighting live candidate routing improvements and current identical behavior.

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

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

Provides a clear when-to-use instruction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the evaluative purpose (results compared against stable router), giving context. However, it does not explicitly state when not to use it or mention the stable ask_pipeworx as the alternative for non-experimental needs.

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 (readOnly, idempotent, openWorld) by disclosing the extra LLM call, the exact refusal reasons, and the guarantee that answers are extracted only from tool results. This provides rich behavioral context without contradicting any annotation.

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

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

The description is well-structured and front-loads the purpose, but it is fairly long due to detailed return/refusal specifications. Each sentence is valuable, yet the length slightly exceeds the minimum needed for this level of complexity, so it is not a perfect 5.

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

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

The description fully compensates for the lack of an output schema by detailing the success return fields and refusal reasons. It also provides context about routing to 5,462 tools and 1419 sources, making the tool's behavior and invocation context complete 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?

The input schema already covers all parameters with 100% coverage, including a clear description of the main 'question' parameter and its aliases. The description adds no additional parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's specific function: 'Hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates it from the sibling ask_pipeworx by describing the extraction behavior. It names the resource and the exact outcome (answer plus evidence) with a specific verb, making it highly distinguishable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and also when to avoid: 'prefer ask_pipeworx for casual lookups.' It names the alternative tool and provides a cost-based rationale for choosing between them.

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

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

Annotations already state readOnly/idempotent/non-destructive, so the bar is lower, but the description goes far beyond: it discloses resolver confidence and alternatives, parent-event extraction, GDELT/GNews fallback behavior, low-confidence short-circuiting, market-closed handling, wide-spread tradeability warnings, and cancellation-rule settlement risks. This is exceptionally transparent.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Most sentences carry substantive behavior information, though it could be more concise without losing value.

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

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

With no output schema, the description carries the full burden of explaining return shapes. It thoroughly covers result.market, result.analysis, result.evidence, resolver contract, parent_event, news fallback fields, safety statuses, and cancellation-rule risk—more than enough for an agent to understand the complex behavior without 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 description coverage is 100%, so the baseline is 3 even without additional parameter detail. The description provides helpful examples of valid market inputs and implies depth default behavior, but it does not add meaningfully beyond the schema's parameter descriptions.

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

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

The description opens with a specific action ('Research a Polymarket bet') and identifies the resource and outcome ('pulling the relevant Pipeworx data... returns an evidence packet'). It genuinely distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges by focusing on data-gathering for a bet rather than edge/arbitrage computations.

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

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

Usage is clearly signaled with explicit use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It also gives blocking conditions (low_confidence_match, market_closed_or_inactive) and safety warnings. However, it doesn't explicitly compare against sibling tools or say when NOT to use it, 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 adds rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format with citation URIs. This fully discloses what the tool does without contradicting annotations.

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

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

The description is dense but efficient, with no filler. It leads with trigger phrases, states the core function, then details data sources and behavior in a logical, front-loaded structure. Every sentence earns its place, conveying maximum information in a compact format.

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

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

Despite having no output schema, the description explains return format (paired data + citation URIs), sorting behavior, and selection criteria. It covers both entity types and parameter semantics fully. The tool's complexity is high, but the description is sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for both parameters, but the description adds significant meaning: it explains what each 'type' value does, gives concrete examples for 'values' (tickers, drug names), and clarifies constraints like 2–5 items. It also notes specifics like 'off-calendar fiscal years handled correctly,' which is not in the schema.

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

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

The description explicitly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and clearly distinguishes it from sequential lookups, making its purpose and scope unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving a clear when-to-use directive. It also specifies the two entity types (company/drug) and the data each pulls, helping the agent decide when this tool is appropriate versus alternatives like entity_profile.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing account requirements, paid tier for 'thorough', expected latency (15-60s), gap[] behavior (never invented), semantic excerpting, citation fetchability, and contradictions[] for specific depths. This provides rich operational context without contradicting annotations.

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

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

The description is dense but well-structured, front-loading the account requirement and core purpose. It covers many nuances (alternative tools, time expectations, citation format) in one paragraph. While every sentence offers value, it is slightly verbose and could be tightened without losing information.

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

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

Despite lacking an output schema, the description thoroughly explains return values: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers limits (empty gaps for non-structured topics) and performance, making it complete for a tool of this complexity.

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

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

Even though schema coverage is 100%, the description adds critical semantics: explaining what each depth level does (quick=single hop, standard=gap recovery + contradictions, thorough=lead chasing + recovery + contradictions). This enriches parameter meaning beyond enum labels, especially for the depth parameter.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, with decomposition and parallel routing to 5,462 tools. It explicitly distinguishes from open-web search and names sibling tool ask_pipeworx for comparisons, making the primary resource and scope 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?

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and mentions using ask_pipeworx if not signed in. This clearly positions deep_research against alternatives, making selection easy.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond the annotations: it returns top-N tools with full input schemas and curated examples, and results are 'ready to call directly, no second schema lookup needed.' This clarifies the output format and efficiency benefits.

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 somewhat long but well-structured: first sentence states purpose, second gives usage context, third explains output format, fourth provides usage priority. The domain list is repetitive but informative. No wasted sentences, though it could be tightened.

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

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

For a tool-discovery tool with no output schema, the description is complete enough. It explains what the tool returns (top-N tools with descriptions and full schemas), when to use it, and provides examples in the schema. The description covers the key decision points 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%; the schema already documents all six parameters including aliases and descriptions. The description mentions 'describing the data or task' and 'top-N' but adds no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and differentiates itself from sibling domain-specific tools by being a meta-search tool. The list of supported domains (SEC filings, FDA drugs, etc.) further clarifies scope.

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

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

The description explicitly says when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It also hints at when not to use it ('not just one answer'), implying direct targeted tools are better when a single answer is needed, though it doesn't name specific alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the tool fans out across multiple sources in a single parallel call, returns specific fields (CIK, filings with URIs, fundamentals, etc.), and notes behavioral quirks like the USPTO PatentsView API sunset with soft-fail and GDELT→GNews fallback. This adds substantial context beyond annotations.

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

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

The description is longer than ideal due to example user phrasings, but they serve a purpose in helping the agent recognize invocation patterns. The core functionality and output list are concise and front-loaded enough after the examples; every piece of extra detail (source list, fallback) is valuable.

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 fully carries the burden of explaining return values: it enumerates cik+company_name, filings count and URI format, fundamentals fields and sorting, patents fallback, news fallback, and LEI. Input constraints and required pre-steps (resolve_entity) are also covered, making it complete for such a complex multi-source tool.

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

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

Schema coverage is 100%, and the description's parameter info (ticker or CIK, names not supported) largely repeats the schema descriptions. It doesn't add new semantics beyond what the schema already states, so the baseline 3 applies.

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

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

The description explicitly states it creates a 'full cross-source profile of a US public company in ONE parallel call', using a specific verb ('profile') and resource ('US public company'). It distinguishes itself from siblings by declaring 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and naming alternative tools like resolve_entity.

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

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

It gives explicit when-to-use guidance ('when the user asks for a holistic view') and when-not-to-use (names not supported, use resolve_entity first). It directly names alternatives and even explains the parallel-call strategy, leaving no ambiguity about when this tool should be selected over siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, establishing the safety profile. The description adds usage context (stale context, sensitive data) but does not disclose additional behavioral specifics such as permanence or side effects. With annotations covering the key traits, this is adequate but not enriched.

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 concise sentences that front-load the purpose, follow with usage conditions, and end with related tools. Every sentence serves a distinct purpose with no redundancy.

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

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

For a single-parameter deletion tool with strong annotations, the description covers purpose, usage context, and related tools. The idempotentHint addresses missing-key behavior, making the description complete for its simplicity.

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

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

The input schema fully describes the 'key' parameter with 100% coverage and an example. The description adds no deeper parameter semantics beyond 'by key,' so it appropriately relies on 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 'Delete a previously stored memory by key,' specifying the exact action (delete), resource (memory), and scope (by key). It differentiates from siblings like remember and recall by focusing on 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?

Explicitly lists when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also directs pairing with 'remember and recall,' providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral detail beyond that: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the process and network dependency, providing context not in the annotations.

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

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

The description is three sentences, front-loaded with the main purpose, then process, then use cases. It is concise and each sentence adds value, though the 'Useful for:' list is slightly verbose and could be trimmed without losing essential meaning.

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

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

Even without an output schema, the description explicitly states the output ('a single text blob ready to drop at site-root/llms.txt') and the standard markdown format. Combined with clear use cases and annotations, the tool is fully described for an agent to invoke correctly. The 2-param schema and annotations complete the picture.

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 both parameters (url and max_links), so the schema already documents them. The description mentions 'extracts title/description/key links' which loosely relates to max_links but does not explicitly explain parameter syntax or defaults beyond the schema. The schema carries the load, 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 the tool's core function: 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It also specifies the target format and audience, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on visibility checking rather than file generation.

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.' It gives clear context for when to use the tool, but does not mention alternatives or exclusions, so it misses the full '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 the tool as read-only, idempotent, and non-destructive. The description adds value beyond annotations by specifying the exact output components (fields, geometry type, total record count, capabilities). No behavioral contradictions exist, and the description aligns with annotations while providing additional context about what the tool reveals.

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

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

The description is a single, well-structured sentence that is front-loaded with the main purpose ('Get an ArcGIS Feature/Map Service layer's schema by url') and then lists the key output attributes. There is zero wasted wording and every element is informative.

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 no output schema, the description provides a comprehensive summary of what the tool returns (fields, geometry type, record count, capabilities). It does not detail the exact response format, but that is not necessary given the tool's simplicity and the clear list of outputs. This is slightly above minimal adequacy.

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

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

The input schema fully documents the single 'url' parameter with an example and description, achieving 100% schema coverage. The description merely restates 'by url' without adding new semantic detail. The baseline of 3 is appropriate since the schema already carries the parameter meaning.

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

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

The description clearly states the tool's purpose: retrieving an ArcGIS Feature/Map Service layer's schema by URL, with explicit details on what is returned (fields, geometry type, record count, capabilities). This is a specific verb+resource combination that distinguishes it from sibling tools like query_layer, which likely fetch data rather than schema.

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

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

The description establishes a clear context: use this tool to get schema information for a layer, not to query features. While it does not explicitly name alternative tools or exclusions, the phrase 'Get an ArcGIS Feature/Map Service layer's schema' makes the intended use unambiguous and distinct from data-querying tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context by noting it returns caller-specific active subscriptions and lists the exact fields included. This supplements the annotations well.

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 main action, and efficiently uses the second sentence for usage guidance. Every word contributes value with no redundancy.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose, return fields, and usage context. It lacks minor details like pagination or sorting, but these are not critical for this type of list operation given the annotations and schema.

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

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

The input schema provides 100% coverage for the single parameter include_inactive, including its default behavior. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifies the returned fields (id, type, params, etc.), and distinguishes it from sibling tools like subscribe/unsubscribe by focusing on listing. It is specific and unambiguous.

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

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

The description explicitly tells when to use this tool: to review current monitoring before adding more or to find a subscription id to cancel. This provides clear context and implicitly ties to alternatives (subscribe/unsubscribe).

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 all annotations set to false (little safety/behavior signal), the description carries the burden and does so thoroughly. It discloses the claim_token return-and-lookup workflow, the daily rate limit of 5 per identifier, that it is free and doesn't count against tool-call quota, and that the team reads digests daily—practical behavioral context far beyond the schema.

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

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

The description is long, but each sentence earns its place: purpose, scope, exclusions, claim-token mechanics, rate limits, and cost. It is dense as a single paragraph and could benefit from light structural separation, but there is no filler or redundancy.

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

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

Given a 4-parameter call with nested objects and no output schema, the description fully covers invocation, response behavior (claim_token), correction/reference workflow, and constraints. It explains the entire lifecycle from filing to reading the resolution, making the tool self-contained and easy 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 baseline is 3, but the description adds meaning by clarifying how to write `message` (specific, 1-2 sentences, no user prompt), how `context` should reference Pipeworx tools/packs, and the special `claim_token` round-trip usage. This transforms the raw schema into actionable guidance, though the enum semantics are already well documented in the schema.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete feedback categories (bug, feature, data_gap, praise) and explicitly scopes the tool to Pipeworx-served tools, distinguishing it from sibling tools like ask_pipeworx.

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

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

It provides explicit triggers: use when a tool returns wrong/stale data, when a desired tool is absent, or for praise. It also gives a clear exclusion—if the tool came from a different MCP server, file elsewhere—and advises describing issues in terms of Pipeworx tools/packs rather than pasting the end-user prompt.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond these: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains the data provenance, privacy aspects, and caching behavior, which are not covered by annotations.

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

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

The description is well-structured and front-loaded with the core function, followed by a concise bulleted list of use cases and then a concise note on data source/caching. It is moderately sized but every sentence adds value, with no filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it states what the tool returns ('top tools, top packs, and total call volume'), provides use cases, and explains the data aggregation and caching. No critical context is missing for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100%, so the input schema fully documents the single 'window' parameter, including enum values and the note 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' The description only repeats this information without adding new parameter semantics, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This is specific with a clear verb ('Returns') and resource (trending call data), and it distinguishes itself from siblings like discover_tools by focusing on aggregate peer usage rather than general tool discovery.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' This gives clear context on when to use the tool, though it does not name alternative tools or specify 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?

Beyond the read-only annotations, the description discloses critical behavioral details: the partition filter with placeholder logic, the semantic anchor requiring ≥0.30 Jaccard similarity, the fill check that prices against live CLOB depth, and the rule that realizable_edge_pp ≤ 0 means no trade. This adds substantial operational context not present in annotations.

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

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

The description is long but well-organized, with clear sections for modes, semantic anchor, partition filter, response, and fill check. It could be tightened (e.g., combining repeated phrases), but every paragraph adds distinct value and the summary sentence front-loads the core purpose.

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

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

With no output schema, the description appropriately explains response fields (opportunities[], partition_check{}, fill check outputs) and all edge-case behaviors. It covers the tool's complexity comprehensively for an agent to invoke it correctly and interpret results.

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

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

Although the schema has 100% coverage, the description enriches the semantics greatly. It explains that 'event' accepts slugs or full URLs and walks child markets, while 'topic' searches related events using a seed question, and details the output structure for each mode. This goes far beyond the schema's one-line definitions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's scope from sibling tools like polymarket_fill_risk and polymarket_edges by detailing its three modes (trending_scan, event, topic) and the underlying detection mechanisms.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends event mode for a specific market and directs users to 'polymarket_fill_risk' for custom sizing, making when-to-use/alternatives unmistakable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is known. The description adds extensive behavioral context: the 24-hour move warning, 'your edge may already be in the price,' placeholder-slug filtering, 'rare-by-design' nature, gate adjustments, diagnostics output, and KV-level caching. It also explains Fed candidates are excluded from ranking. This goes far beyond the annotations and provides valuable transparency.

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 an extremely long, dense wall of text with no formatting (no paragraphs, bullets, or section headers). It covers five model families, three response segments, knobs, diagnostics, and caching, but is hard to parse. While most sentences carry technical information, the lack of structure makes it less scannable for an agent. It is not 'concise' in any sense.

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 is remarkably complete for a complex tool with 9 parameters. It explains the top-level response fields (by_segment, fed_candidates/fed_note, _diagnostics), lists what each opportunity carries (edge_pp_net, kelly_fraction, etc.), and describes filtering behavior and caching. An agent can infer the output structure and invocation semantics without 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 coverage is 100% (all 9 parameters have descriptions), so the baseline is 3. The description adds extra semantics on top: it explains that min_kelly never filters partition_overround opportunities because they return kelly_fraction_half=0 at the parent level, and that min_partition_leg_kelly is the proper knob for those. It also frames min_liquidity and max_spread_pp as 'tradeable-edge' filters, which adds conceptual meaning beyond the schema.

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

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

The description clearly states the action and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also clarifies the scope ('without paging hundreds of markets'). However, it never explicitly distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, only describing its own internal segments rather than naming alternatives.

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

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

The description provides strong usage context: 'Built for "what should I bet on today"' and 'agents discover opportunities without paging hundreds of markets.' This implies when to use the tool. However, it does not explicitly state when not to use it or point to sibling tools as alternatives, so exclusions are missing.

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

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

Annotations only declare readOnly/idempotent/non-destructive; the description adds substantial behavioral context: snapshot writes only on cache-miss, gaps mean no scan that day, 60-day TTL limits history, and decay is computed from daily closes of edge_pp_net, not intraday. This goes far beyond annotation hints.

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

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

The description is longer than average but well-organized with RESPONSE and LIMITS sections. Every sentence contributes either to explaining the response structure or to conveying data caveats, though some redundancy exists with the schema's parameter descriptions.

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 specifies the response shape: tracked[] with fields like first_seen, trend, decay_pp_per_day; expired[] with lifespan_days; and snapshot_dates[] with missing-day semantics. It also covers data limitations and computation method, making it complete for a telemetry tool.

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

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

The input schema already documents both parameters thoroughly (days with default/clamp, window with allowed families and default). The description repeats the defaults but adds no new semantic detail beyond what the schema provides, so it meets 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 specifies a concrete purpose: 'edge persistence and decay telemetry' built from snapshots, and answers the question 'how long has this edge existed and is it shrinking?'. It clearly distinguishes itself from the sibling tool 'polymarket_edges' by focusing on time-series trends rather than 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 explains when to use it (to assess edge age and decay) and provides contextual reasoning ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when not to use it, leaving some usage boundaries implied.

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 declaring read-only, idempotent, and non-destructive behavior, the description adds significant behavioral context: it details mode-specific execution (walking the ladder, basket settlement notional), return fields, and risk factors like forced_directional_risk and the dangers of partial basket fills. This goes far 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?

While long, the description is meticulously structured with uppercase section labels (SINGLE-MARKET, BASKET, USE THIS) and every sentence conveys essential information. It avoids filler and presents dense, actionable details appropriate for the tool's complexity.

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

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

With no output schema present, the description compensates fully by listing all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realization, capture_ratio, thin_legs, etc.) and explaining both usage modes, parameter interpretations, and risk guidance. It is a complete standalone reference 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?

The schema descriptions are already thorough (100% coverage), but the tool description adds critical mode-specific semantics: size_usd means 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional S (shares per leg)' in basket mode. It also clarifies the REQUIRES one-of-market-or-event constraint, which the schema does not enforce.

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

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

The description opens with a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then clearly distinguishes between single-market and basket modes, making it obvious what the tool does and how it differs from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The tool explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why theoretical overround is not capturable and warns about partial fills, providing strong decision guidance beyond just 'when to use.'

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent) by detailing response behavior and safety fields: compatibility_warning conditions, temporal_alignment implications, and skipped_cross_type/subtype counters. It transparently discloses limitations such as when matched_pairs:0 means events are unrelated and when spreads are meaningless across temporal gaps. No contradiction with annotations.

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

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

The description is long and dense, but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides functional information, though some sentences are convoluted (e.g., the parentheticals about cross-type/subtype). It is appropriately sized for the tool's complexity, but not as concise as it could be.

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

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

There is no output schema, so the description takes on the burden of explaining return values. It does so thoroughly: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning with two distinct cases, temporal_alignment, and skipped_cross counters. It also covers edge cases and limitations, making it complete for a tool of this complexity.

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

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

All three parameters have full schema descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the interaction between parameters: topic as a pre-mapped shortcut vs explicit kalshi_event_ticker + polymarket_event_slug for custom pairings, and how explicit overrides work. This mode-level semantics is not fully present in the schema, justifying a 4.

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

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

The description clearly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (Kalshi and Polymarket events) and the action (computing spread), and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The two modes and response summary further clarify its unique purpose.

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

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

The description provides clear usage context by explaining two modes (topic shortcuts vs explicit tickers) and cautions that pre-mapped topics often return compatibility warnings. It includes practical guidance like 'pre-mapped ≠ tradeable.' However, it does not explicitly name alternative tools or state when not to use this tool (e.g., for single-venue arbitrage), so it stops short of full when/when-not guidance.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context beyond annotations by specifying that the tool 'Returns attribute rows (and geometry)', which clarifies the output format. It also mentions the sampling technique. No contradictions found.

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

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

The description is two sentences long and front-loaded: the first sentence states the purpose and key parameters, the second provides a practical tip. Every sentence earns its place with zero waste. This is a model of concise, structured tool documentation.

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

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

The tool has 6 parameters all documented with 100% schema coverage, so the description doesn't need to repeat parameter details. It does explain the return type (attribute rows and geometry) which is important since there is no output schema. The note about search_datasets gives workflow context. Missing some details like error behavior or rate limits, but these are less critical for a read-only query tool with rich annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the key parameters (where, out_fields, order_by, limit, offset) and gives a usage example, but it largely restates the schema. It does not add significant new semantics beyond what the schema already provides, so a 3 is appropriate.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. The verb 'Query' is specific, the resource is identified, and the origin from search_datasets differentiates it from siblings like layer_info (which likely fetches metadata) and search_within (which likely performs spatial search).

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

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

The description provides clear context for when to use the tool: to query a layer by URL, and it even gives a concrete usage tip ('Use where="1=1" + out_fields="*" to sample'). It implies usage in conjunction with search_datasets, but does not explicitly mention alternatives or exclusions, so I deduct one point for not explicitly differentiating from sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context about scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also clarifies the two operating modes (retrieve by key vs. list all). No contradiction with annotations; the added context enhances understanding beyond the structured hints.

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

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

The description is four sentences, front-loaded with the core action. Every sentence adds value: the primary function, concrete use cases/examples, scoping detail, and pairing with companion tools. No redundant fluff or repetition of structured data. Appropriately sized for the tool's simplicity.

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 low complexity (one optional parameter, no output schema), the description is complete. It covers both invocation modes, the purpose with concrete examples, scoping, and relations to sibling tools. There is no missing information that would prevent an agent from using the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the optional 'key' parameter and the 'omit to list all keys' behavior. The description reinforces this but does not add significant new meaning beyond the schema. It hints that keys come from 'remember', which is a minor addition, but overall the parameter semantics are adequately handled by the schema.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs ('retrieve', 'list') and a specific resource (saved keys/values), and differentiates from sibling tools by explicitly mentioning 'remember' and 'forget'. This is a textbook example of purpose clarity.

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

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

The description gives explicit when-to-use context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also mentions complementary alternatives ('Pair with remember to save, forget to delete'), but does not explicitly state when not to use this tool or offer an alternative for the same lookup purpose. Clear context, but lacks direct 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 states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing operation. This directly contradicts the readOnlyHint:true annotation, creating a significant conflict in understanding the tool's 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 three sentences, front-loaded with the main purpose, and every sentence adds value: purpose, return contents, filtering, mark_read behavior, and an alternative access method. It is concise and well-structured.

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

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

Despite having no output schema, the description informs the user that each event carries source, citation_uri, and raw payload, which is helpful. It covers filtering, mark_read, and the HTTP endpoint. It does not explicitly mention unread_only, but the schema covers that, and the overall package is complete for a polling 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?

All five parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds an example for type ('sec_8k') and clarifies the consequence of mark_read ('the next call only shows newer ones'), but does not add meaning for limit or unread_only beyond what the schema already provides.

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

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

The description opens with a specific action: 'Pull fired events from your subscription feed.' It clearly distinguishes this from sibling tools by stating it returns recent alerts with source, citation_uri, and raw payload, making its unique purpose evident.

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 notes that 'Polls work fine' and provides an HTTP alternative, 'GET registry.pipeworx.io/alerts.json', for scripts and dashboards. This gives clear context on when to use the tool vs an alternative, though it does not explicitly contrast with sibling tools.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing the fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-fail behavior. It also mentions the PatentsView API sunset and the non-blocking nature of that source. This gives the agent a clear model of side effects and dependencies.

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 clause earns its place. It starts with recognizable query patterns, states the mechanism, lists sources and fallbacks, covers date syntax, describes the output structure, and gives an explicit alternative—all in a compact paragraph 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?

With no output schema, the description still explains that it returns "structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs." It also covers edge cases like GDELT rate-limit fallback and USPTO soft-fail. For a tool with this complexity and no output schema, the description is remarkably 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?

Although the schema already describes each parameter, the description adds crucial semantics: `since` accepts ISO or relative shorthand, and "Use '30d' or '1m' for typical monitoring." It also explains how `value` maps to a ticker or CIK and how the window applies across all sources. This enrichment helps correct parameter usage.

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

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

The description opens with concrete user phrasing ("What's new with X") then states the core action: "change feed for a company in the last N days/weeks/months in ONE parallel call." It also explicitly distinguishes itself from sibling entity_profile, naming the alternative for static profiles. This leaves no ambiguity about the tool's role.

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

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

Provides direct usage context with example queries and clearly states when to prefer a different tool: "Use entity_profile instead when you want the static profile... regardless of window." It also explains fallback behavior for news sources, which helps an agent decide when this tool is appropriate.

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

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

Discloses behavioral details beyond annotations: key-value scoping by identifier, persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'), and cross-session retention. No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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, each earning its place: purpose, when-to-use, and storage behavior/pairing. Front-loaded with the core verb 'Save' and highly efficient with no redundant wording.

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 2-parameter store operation with no output schema, the description covers purpose, usage criteria, persistence, scoping, and companion tools. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the concept of 'key-value pair' and scoping, but the schema already provides clear descriptions for 'key' and 'value'. No additional parameter-level semantics beyond what is 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 a specific verb+resource: 'Save data the agent will need to reuse later', and distinguishes this from sibling tools by explicitly pairing with 'recall' and 'forget', positioning it as the write operation in a memory system.

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

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

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'), and mentions complementary tools ('Pair with recall to retrieve later, forget to delete'), giving clear context without needing 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?

Beyond annotations (readOnly, idempotent), the description discloses internal behavior: it cascades through multiple lookup endpoints, auto-disambiguates input, and returns citation URIs. This adds valuable context not present in annotations.

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

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

The description is a bit long but well-organized with examples, supported types, and output details. Every sentence adds value, though the opening quotes could be trimmed without losing meaning.

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 specifies return values (CIK, ticker, company_name, RxCUI, brand, citation URIs) and covers both supported types. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful examples for both parameters (AAPL, CIK format, ozempic) and clarifies accepted input formats (ticker vs name), exceeding schema descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical/official identifier, with specific verb and resource. It provides concrete examples of queries and supported types, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and what each returns. However, it does not explicitly mention alternatives or when not to use this tool, which would make it a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. This goes beyond the annotations by disclosing the internal call pattern and output structure.

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

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

The description is concise (two sentences plus a brief example) and front-loaded with the core purpose. Every sentence earns its place: purpose, mechanism, use case, and output. No redundant wording.

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

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

Given the tool's complexity, the description is complete: it explains the side-by-side comparison, underlying calls to ai_visibility_check, ranking logic, output metrics, and a sample use case. The schema fully documents parameters, and the description covers the return value, so no critical information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-level meaning beyond the schema: it mentions 'your brand + N competitors' which aligns with the schema's note about the first entry being the subject, but it does not explain any parameter details that the schema doesn't already provide.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' with specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes itself from sibling tools like 'ai_visibility_check' (single-entity) and 'compare_entities' (generic comparison) by focusing on AI visibility and competitive ranking.

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: 'Useful for competitive AI-marketing audits' and gives a concrete example. It implicitly differentiates from single-entity 'ai_visibility_check' by emphasizing side-by-side comparison across multiple entities, but does not explicitly state when not to use it or name alternative tools for exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: partial failures degrade gracefully, first bundlephobia measurement can take 5-30s, sources_failed lists timeouts. It also clarifies ecosystem limitations (NPM only in v1). This goes well beyond the annotations.

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

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

Though slightly long, every sentence is information-dense and front-loaded with the core purpose. It efficiently lists return fields inline and uses dash separators for readability. No redundancy with the schema; all content adds value.

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

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

In the absence of an output schema, the description fully elaborates return fields (summary block, per-advisory detail, links, recent versions), limitations (NPM only, possible timeouts), and failure behavior. It gives an agent complete context to invoke successfully and interpret results.

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

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

Schema description coverage is 100% — both package and version have clear schema descriptions. The tool description adds no new parameter semantics beyond what the schema already provides (e.g., version defaults to latest when omitted is already in the schema). Baseline 3 is appropriate given 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 states a clear, specific purpose: 'should I add this npm package to my project check in ONE call' and specifies the data sources (deps.dev, bundlephobia) and what they provide (license, advisories, bundle size, etc.). It distinguishes from sibling tools by its unique scope (npm ecosystem dependency analysis) and is not a tautology.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also contrasts with alternatives for other ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', helping an agent choose 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns dataset name, summary, record_count, owner/org, and a Feature Service URL, which is useful but not rich in additional behavioral context like rate limits, pagination, or auth. This is on par with the calibrated baseline for read-only tools 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 exactly two sentences, front-loaded with the verb and resource, and contains no redundant phrases. It mentions the return fields, the URL, and the next step, all in a compact format. 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 simple search tool with three optional params and complete schema descriptions, the description covers the purpose, output content, and intended workflow (pass URL to query_layer/layer_info). The absence of an output schema is compensated by the description's explicit list of returned fields. The tool's context is fully explained.

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 has 100% coverage with descriptions for all three parameters (limit, query, org_id). The description adds no extra parameter-specific semantics beyond referring to 'by keyword', which maps to query. Since the schema carries the full burden, 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 the verb 'Search', the resource 'City of Novi GIS open geospatial datasets', and the action's scope (by keyword). It distinguishes itself from sibling tools like query_layer and layer_info by explicitly describing what it returns (dataset metadata and a URL) and how to proceed with that URL.

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

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

The description provides clear usage context: it's the discovery tool for datasets, and it instructs the user to pass the returned URL to query_layer/layer_info for further data retrieval. It doesn't explicitly compare against all alternatives, but the workflow is unambiguous and gives enough guidance for when to use this tool vs. its siblings.

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

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

The description goes well beyond the annotations by disclosing truncation at 200K chars, the BGE-base-en embedding model, 500-char overlapping windows, and cosine similarity. It also explains the output includes character offsets for verbatim verification and that longer inputs are flagged. No contradiction with the readOnlyHint=true or idempotentHint=true annotations.

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

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

The description is three sentences with no fluff: the first states the core function, the second gives usage guidance, and the third reveals implementation details. Every sentence earns its place, and the most critical information is front-loaded.

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

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

Despite lacking an output schema, the description explains what is returned ('top-N passages with character offsets and similarity scores'), the hard limit of 200K chars with truncation behavior, and the intended integration with ask_pipeworx_grounded. For a 3-parameter tool, this is fully self-sufficient and leaves no major gaps.

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

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

The input schema already provides comprehensive descriptions for all three parameters, including examples for query and constraints for text (max ~200K) and limit (1-20, default 5). The description reinforces that text is 'already pulled' content but adds no new parameter-specific syntax or constraints. Since schema_description_coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record', a specific verb+resource that immediately distinguishes it from sibling tools. It provides concrete examples (SEC 10-K, article) and explicitly differentiates from ask_pipeworx_grounded by explaining it searches within provided text rather than external sources. This leaves no ambiguity about what the tool does.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt' and highlights the benefit of saving context. It also names a sibling tool (ask_pipeworx_grounded) and describes a clear workflow: fetch with the gateway, ground over relevant passages. This provides both when-to-use and a contrast with the alternative.

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

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

Beyond annotations, the description discloses that phone verification is needed for SMS, a 10/day cap exists, and webhook is auto-disabled after 10 consecutive failures. It also mentions the one-time return of the signing secret, which is critical behavioral context not available in annotations.

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

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

The description is front-loaded with purpose, then covers requirements, types, and delivery options in a logical order. Though lengthy, every section supports correct invocation; minor redundancy with schema descriptions prevents a perfect score.

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

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

The description covers authentication requirements, all supported subscription types with examples, delivery channels and their constraints, and the return value (subscription id). Given no output schema exists, this provides complete guidance for a complex invoke scenario.

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

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

Schema coverage is 100%, but the description adds practical meaning by giving concrete examples (e.g., items:['5.02'] = officer change, params:{topic:'fed'}) and explaining delivery channel behavior such as webhook HMAC signing. This goes beyond the schema's already detailed parameter descriptions.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream' — a specific verb and resource, clearly distinguishing it from sibling tools like unsubscribe or list_subscriptions. It also names supported subscription types, further clarifying the tool's scope.

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

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

It states the prerequisite of a Pipeworx OAuth account and notes that anonymous/BYO cannot persist, setting clear expectations. It also implies a contrast with polling via recent_alerts for the always-on feed, but does not explicitly name alternatives or say 'use this instead of that'.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the safety profile is covered. The description adds valuable behavioral context: it returns 'category-bucketed example questions' with 'the exact tool + argument shape,' drawn from the live catalog, and explains the topic-focused versus full-spread behavior. This goes well beyond what annotations convey.

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

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

The description is long but well-structured: it front-loads common user phrasings, states the purpose, then details output and parameter behavior. Every sentence contributes to understanding, though the list of example phrasings is slightly redundant and could be trimmed without losing meaning.

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

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

The tool has no output schema, but the description fully explains what is returned (category-bucketed example questions with tool+argument shapes) and the parameter behavior. Given its simplicity (one optional parameter) and clear annotations, the description is complete for an onboarding/discovery tool.

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

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

The schema covers the only parameter 'topic' with a description and allowed values (100% coverage), so the baseline is 3. The description enhances this by giving concrete examples ('finance', 'pharma', 'betting') and explaining the effect of omitting vs. passing the parameter, adding real semantic value beyond the schema.

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

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

The description clearly states the tool is 'the onboarding entry point' for an agent to learn what Pipeworx can do, which is specific and result-oriented. It distinguishes itself from siblings by saying to use it FIRST to learn how to call meta-tools like ask_pipeworx and entity_profile, and by noting it returns example questions with exact tool+argument shapes.

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

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

The description gives explicit usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also specifies call patterns (no arguments for full spread, or pass 'topic' to focus). However, it does not explicitly state when NOT to use the tool in favor of an alternative, so it falls slightly 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?

The description adds valuable behavioral details beyond the annotations: ownership enforcement and the fact that the row is deactivated rather than deleted, preserving historical events in recent_alerts. These details are not present in the annotations, which only provide generic hints (readOnly=false, destructive=false, idempotent=true).

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: purpose, constraint, and effect. Each sentence contributes unique information, no redundant phrasing, and the most important action is front-loaded.

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

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

For a simple single-parameter tool, the description covers purpose, ownership rule, and side effects. However, with no output schema, it does not describe the return value or response format, which would be useful for an agent to know what to expect. This is a minor gap given the tool's simplicity.

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

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

The schema already documents the id parameter with 100% coverage, so the baseline is 3. The description adds the ownership constraint directly relevant to the parameter (only your own ids), and reiterates that the id is a subscription id. This adds meaning beyond the schema's basic type and source.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb-resource pairing. It clarifies the soft-delete behavior, distinguishing it from a hard delete, and is clearly distinct from sibling tools like subscribe and list_subscriptions.

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

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

The description clearly identifies the action, but does not explicitly state when to use this tool versus alternatives, nor does it mention not to use it in certain situations. While the ownership constraint provides a usage condition, there is no explicit guidance on when to prefer this over other tools, making the usage implied rather than explicit.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description does not contradict these. It adds substantial behavioral detail beyond annotations: the two routing paths, the verdict categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), the inclusion of verbatim evidence with pipeworx:// citation, and the tolerance_pct override semantics (e.g., set 1–2 for hallucination detection). This deeply discloses how the tool behaves in different scenarios.

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

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

The description is dense but front-loaded with the core purpose and user intents, then covers routing, output, and efficiency. It is longer than average but every sentence contains unique information (routing logic, verdict types, replacement claim). It could arguably be trimmed, but the structure is clear and no content is extraneous.

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

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

Given the tool's moderate complexity, the description is highly complete: it explains the two routing strategies, the return verdict types, the citation/reasoning output, the tolerance behavior, and the efficiency advantage over multi-step alternatives. Since there is no output schema, the description properly fills in the return-value expectations, making the tool fully understandable to 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?

Both parameters (claim and tolerance_pct) have thorough descriptions in the input schema, achieving 100% schema description coverage, so the baseline is 3. The tool description adds no extra parameter-level meaning; it references 'exact percent-delta math' and 'tolerance' but these are already captured in the schema's tolerance_pct description. Thus the description does not need to compensate and doesn't go beyond the schema.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with a specific verb (validate) and scope (claim verification). It distinguishes from siblings by mentioning the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others) and by claiming to replace 4–6 sequential calls, making its role unique among tools like ask_pipeworx and deep_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear trigger. It also differentiates when to use the internal fast path vs the grounded pipeline, though it doesn't explicitly name alternative tools to avoid. The claim that it replaces 4–6 sequential calls implies it should be preferred over composing other tools, but exclusions are not spelled out.

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