Arcgis Cupertino

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context: the default Workers AI model is free, Anthropic requires a BYO key and results in direct charges, and the API key is passed through to api.anthropic.com. It also discloses the return structure. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core action and outcome, followed by model options, return format, and use cases. Every sentence adds distinct value with no fluff or redundancy.

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

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

With no output schema, the description clearly states the per-model and combined return shapes, and it covers the main behavioral nuances (default model, optional Anthropic key, cost implication). It could mention what 'signals' represent or error handling, but for a read-only probe tool, the provided information is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats some parameter nuance (e.g., '_apiKey' enables Anthropic, default model is workers-ai) but does not add meaning beyond the schema's own descriptions. It earns the baseline but no more.

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 ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic'), then clearly states the scoring output (0-100 per model). It distinguishes this from sibling tools by focusing on AI visibility measurement rather than general Q&A (ask_pipeworx) or one-off scans (scan_competitor_ai_presence). The use cases at the end reinforce 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 gives clear context for when to use the tool ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and how to opt into Anthropic. It does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the tool routes to 5,563 tools, fills arguments, and returns structured answers with stable citation URIs. It does not contradict annotations but could disclose rate limits or auth needs.

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

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

The description is detailed but front-loaded with the key guidance 'PREFER OVER WEB SEARCH'. It is structured with clear sections for use cases, examples, and escalation paths. Slightly verbose due to list of example sources and queries, but every sentence serves a purpose for an agent's decision making.

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

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

Given no output schema, the description compensates by describing the return format ('structured answer with stable citation URIs'). It covers scope, alternatives, example queries, and tool routing behavior. For a tool with 6 parameters (1 required) and rich sibling context, the description is fully adequate.

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 parameters are fully documented. The description goes beyond by providing rich examples (e.g., 'What was Apple's revenue in 2024?') that illustrate acceptable question formats. It also mentions aliases (query, q, text, input) which adds value for agent flexibility.

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 the verb 'ask' and the resource 'Pipeworx', clearly stating it routes questions to over 5,000 tools across verified sources for authoritative structured data. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explicitly noting when to step up to those 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 extensive guidance: prefer over web search for factual questions, start here as default entry point, and explicitly names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions, breaking-news routing for current events). It even lists example query starters like 'what is' and 'look up'.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by explaining the experimental nature, the testing process, current state (no candidate active, matches stable), and that it's a full working router (not a fallback). This goes beyond the annotations.

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

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

The description is three sentences, well-structured, and front-loaded with key information. Each sentence adds value, though it could be slightly more concise by removing the explicit date or minor details.

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

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

Given the complexity (experimental variant of a large tool) and no output schema, the description covers the nature, current behavior, and comparison to stable. It is sufficiently complete for an agent to understand how to use this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters and their aliases. The description adds no additional parameter semantics. Baseline 3 is appropriate as the description does not need to compensate.

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

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

The description explicitly states 'Beta version of ask_pipeworx: identical universal router' and distinguishes it from the stable sibling by labeling it as experimental with candidate routing improvements. It clearly identifies the tool's purpose and resource.

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 says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared to the stable router. It provides clear context for when to use, but does not explicitly state when to avoid (e.g., for production reliability), though the 'beta' label implies caution.

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, destructiveHint=false. The description adds significant behavioral context: refusal reasons, return format (answer, evidence, confidence, source, fetched_at, refusal_reason), and extra cost ('one extra LLM call vs ask_pipeworx'). No contradictions.

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

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

The description is front-loaded with the core purpose ('Hallucination-resistant answer mode for high-stakes reads') and well-structured. However, it is somewhat verbose (e.g., listing all refusal reasons in detail could be shortened). Still efficient for the complexity it covers.

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 (high-stakes grounded answers, multiple refusal modes, cost trade-off), the description covers all essential aspects: purpose, usage, behavior, return format, refusal reasons, and cost. No output schema exists, so the description fully compensates by explaining the response structure.

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 6 parameters (all aliases for 'question') with 100% description coverage, so the schema already documents each alias. The description adds context about how the question is used (routing, argument filling, data fetching) but does not add syntactic or semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by specifying it 'EXTRACTS the answer using ONLY what the tool result contains.' The verb+resource+scope is specific and 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?

Explicitly tells when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). Includes concrete use cases (financial verdicts, legal claims, medical lookups, public statements).

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, openWorldHint=true, destructiveHint=false, establishing a safe, non-destructive profile. The description goes far beyond this by disclosing critical behavioral traits: low-confidence matches short-circuit with status:"low_confidence_match", closed/dead markets trigger status:"market_closed_or_inactive", wide-spread markets carry tradeability:"illiquid_wide_spread", and resolution-rule risk is parsed (cancellation_rule). It also explains news fallback mechanisms (_fallback_attempted, retry_after_sec) and the blocking nature of both resolution paths. This is a textbook example of adding context beyond annotations without contradiction.

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

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

The description is long (≈350 words) but extraordinarily well-structured with capitalized section headers (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loaded purpose statement. Every sentence adds substantive detail—examples of fan-outs, safety protocols, and rule risks are directly actionable. It could be tightened, but for a tool of this complexity, the density is justified. Not a 5 because it's verbose, but not lower because of excellent organization.

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 carries the full burden of explaining return values. It comprehensively details all response fields: result.market (bid/ask/spread/liquidity/price changes), result.analysis (model_probability, edge_pp, kelly_fraction_half, 24h-move warning), result.evidence, resolver contract (match_confidence, match_score, alternatives, suggestions), parent_event extractor, news fallback fields, and three distinct statuses (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread). It even covers a nuanced rule-based risk (cancellation_rule). For a 3-parameter tool with this complexity, the context is complete.

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

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

Schema description coverage is 100%: all three parameters (market, depth, include_raw) have detailed descriptions. The tool description adds context about the market parameter's accepted formats (slug, URL, question text) but this is already stated in the schema. The fan-out examples and response shapes are not parameter-specific. Since the schema does the heavy lifting, 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details the full process (resolve, classify, fan out, return evidence packet + comparison) and explicitly lists example use cases ('should I bet on X', etc.). This clearly distinguishes it from sibling tools like polymarket_edges or validate_claim, which focus on narrower outcomes.

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

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

The description provides explicit use-case triggers: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This establishes clear context for when to invoke the tool. However, it does not mention alternatives or when-not-to-use scenarios, so it falls short of a 5, which requires explicit exclusions or alternative tool references.

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, but the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and return of paired data + citation URIs. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose: trigger examples, usage preference, data specifics, sorting behavior, replacement of multiple calls. It is front-loaded with examples and compactly conveys a lot without filler.

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

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

Despite no output schema, the description fully covers what the tool does, what data it returns, how it sorts, and what citations are included. It also handles edge cases (off-calendar fiscal years) and gives parameter constraints in prose. Complete for an agent to 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 goes beyond the schema by detailing what each type value does (company → 10-K data, drug → FAERS/trial counts) and how values are interpreted (tickers/CIKs vs drug names). This extra semantic layer earns 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 is explicit: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides natural-language trigger phrases ('X vs Y', 'which is bigger') and immediately distinguishes itself from sequential lookups. The verb 'compare' and resource scope are crystal clear.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and explains when to use type='company' vs type='drug'. Gives clear context for choosing this tool, and the phrase 'Replaces 8–15 sequential lookups' reinforces the usage advantage.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: parallel decomposition, facet routing, return format (verbatim evidence, confidence, source, citations, gaps[], contradictions[]), semantic excerpting, hop fields, expected latency. No contradictions with annotations.

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

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

The description is detailed but front-loaded with critical information (account requirement, alternative). Each sentence serves a purpose, though some redundancy exists (e.g., repeating 'gap recovery' and 'contradictions[]'). Could be slightly more concise, but 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?

Given the tool has 2 parameters, no output schema, and moderate complexity, the description is exceptionally complete. Covers account tiers, alternative tools, expected latency, return format details, edge cases (gaps[], contradictions[]), and second-hop behavior. No missing information for an agent to select and invoke correctly.

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

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

Schema covers both parameters with descriptions. The description enriches them significantly: explains depth levels (quick=3, standard=5, thorough=8) and their behaviors (gap recovery, contradiction scan, iterative hop), and clarifies that question can be broad/multi-part. Schema coverage is 100%, but description adds unique value beyond enum labels.

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

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

Description clearly states it performs grounded multi-source research over 1462 structured data sources, distinguishing itself from sibling tools like ask_pipeworx (single lookup) and open-web search. Uses specific verbs ('decomposes', 'routes', 'returns') and explicitly names the resource (Pipeworx structured data sources).

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

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

Explicitly tells when to use (broad/multi-part research over structured data) and when not to use (breaking news, current events). Provides alternative tools (ask_pipeworx, ask_pipeworx for news) and account requirements. No ambiguity.

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 the safety profile is known. The description adds valuable behavioral context beyond annotations: it returns top-N tools with names, descriptions, and full schemas, and notes that results are 'ready to call directly, no second schema lookup needed.' This discloses the output format and efficiency, which is 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 front-loaded with a one-sentence summary, followed by usage context and output details. Every sentence earns its place: purpose, domain list, return format, and priority directive. The domain list is long but directly informative, and there is no fluff or repetition.

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

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

Given that this is a meta-tool with no output schema, the description explains its return value thoroughly (tool names, descriptions, full schemas, curated examples) and provides strong contextual guidance ('Call this FIRST'). It covers when to use, what to expect, and how the results are actionable, making it complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100% and all six parameters have clear descriptions, including the main 'query' parameter with examples. The description does not add significant parameter-level details beyond the schema; it focuses on behavior and usage. This matches the baseline of 3 when the schema fully documents parameters.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifically identifies the resource (the tool catalog) and the action (browse, search, look up, discover). It distinguishes itself from sibling domain-specific tools by being a meta-tool that returns tool names, descriptions, and schemas.

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

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

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives a clear directive on when to use it and implies that if you already know the exact tool, you might not need it.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description enriches this with concrete details: parallel fan-out across multiple data sources, the exact return structure, patents API sunset soft-fail behavior, GDELT→GNews fallback, and LEI retrieval. No contradictions with annotations.

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

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

The description is dense but well-structured, with a clear front-loading of example queries followed by a definition of the tool's output. Each clause contributes value, though the opening list of examples could be slightly trimmed without losing clarity.

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

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

Even without an output schema, the description fully compensates by enumerating the exact return fields (CIK, company name, filings with URIs, fundamentals, patents, news, LEI) and behavioral nuances like soft-fail and fallback mechanisms. This gives the agent complete context for invocation and result interpretation.

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

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

The input schema already provides 100% parameter documentation, including example tickers, CIK format, and the restriction that names are not supported. The description reinforces this but adds little new parameter-level meaning beyond what the schema already explains.

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: generating a full cross-source profile of a US public company. It provides multiple trigger-phrase examples (e.g., 'Tell me about X', 'company profile for Microsoft') and differentiates itself from sibling tools like resolve_entity and single-pack lookups by emphasizing the holistic, one-call approach.

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

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

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells users to use resolve_entity first if they only have a name, offering a clear alternative for that scenario.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate those. It adds a small amount of context by explaining the purpose ('clear sensitive data'), but does not disclose any additional behavioral traits such as behavior when the key doesn't exist or return format. This is reasonable for a simple delete tool with strong annotation coverage.

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: three sentences, each earning its place. It front-loads the core action, then provides usage guidance, and finally names related tools. No redundancy or fluff.

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

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

This is a simple tool with a single required parameter, no output schema, and comprehensive annotations. The description explains what it does, when to use it, and how it relates to siblings. It is fully sufficient for the agent to select and invoke the tool correctly.

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

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

The schema has 100% parameter description coverage, with 'key' already documented as 'Memory key to delete'. The tool description adds no extra parameter-specific detail, and the baseline is 3 given high schema coverage. It is sufficient but not enhanced.

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

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

The description clearly states the action: 'Delete a previously stored memory by key', which is specific and unambiguous. It also distinguishes itself from siblings by explicitly mentioning 'Pair with remember and recall', showing how this tool fits with related memory operations.

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 conditions for use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names alternatives (remember and recall) to position this tool correctly among them, giving the agent clear 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, covering the safety profile. The description adds behavioral detail by explaining the process (fetches the page, extracts title/description/key links, emits standard markdown) and the exact output form (single text blob for site-root/llms.txt). This complements the annotations without contradicting them.

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

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

The description is three sentences, each earning its place: the first states the purpose, the second outlines the process, and the third lists use cases. It is front-loaded with the core action and avoids redundancy or filler.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (a single text blob in standard llms.txt markdown), how it works, and when to use it. With only two simple parameters and no nested objects, the description fully covers the necessary context for an agent to invoke the tool correctly.

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

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

The input schema provides descriptions for both url and max_links, achieving 100% coverage. The description does not add significant semantics beyond the schema—'any URL' and 'standard llms.txt format' are already implied. With schema coverage high, the baseline of 3 applies; the description offers only marginal additional parameter-related context.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly states the tool's function (fetches, extracts, emits) and distinguishes it from siblings like scan_competitor_ai_presence by focusing on producing the standard llms.txt markdown format rather than analyzing AI presence broadly.

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

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

The 'Useful for:' section lists three concrete use cases (client indexing, personal project drafting, competitor auditing), providing clear context for when to apply the tool. It does not explicitly mention alternatives or exclusions, but the use cases effectively guide selection among siblings like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact informational payload (fields, geometry type, record count, capabilities), which is behavior beyond the annotation safety profile. No contradictions.

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

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

The entire description is one sentence, front-loaded with the verb and resource, and every word adds meaning. No filler or repetition.

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

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

For a simple 1-param read-only tool with comprehensive annotations and a clear input schema, this description covers all essential context: what it gets, from where, and what it returns. An output schema is not needed given the explicit list of return values.

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

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

The input schema fully documents the single url parameter with an example, and schema description coverage is 100%. The description merely repeats 'by url' without adding format details, validation rules, or edge cases, so it's at the baseline.

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

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

The description uses the specific verb 'Get' with a clear resource 'ArcGIS Feature/Map Service layer's schema' and enumerates concrete outputs (fields, geometry type, record count, capabilities). This distinguishes it from siblings like query_layer, which presumably returns data, not schema.

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

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

The description clearly indicates the tool is for retrieving schema information by URL, implying it should be used when the user needs layer metadata rather than actual features. However, it does not explicitly name alternative tools or state 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?

Annotations already cover the read-only, non-destructive nature. The description adds meaningful context: it scopes to the caller's own subscriptions and lists the return fields, which is beyond what the annotations provide.

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

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

The description is two sentences, well-structured with the action first, followed by return fields, then use cases. No unnecessary words.

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

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

For a simple list operation with one optional parameter and no output schema, the description provides the action, the output shape, and usage guidance. It is fully sufficient for an agent to select and invoke the tool.

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

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

The single parameter include_inactive is fully described in the schema with a clear default, so the description doesn't need to repeat it. Schema coverage is 100%, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: listing the caller's active subscriptions. It also enumerates the return fields, making it distinguishable from sibling tools like subscribe or unsubscribe.

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

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

The description explicitly says when to use it: to review current monitoring before adding more or to find an id to cancel. It does not name alternative tools explicitly, but the use cases are clear enough to guide selection.

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

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

Annotations only provide readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which are minimal. The description richly supplements them by disclosing behavior such as returning a claim_token when filing without an account, using that token later to read resolution status, rate limiting to 5 per identifier per day, and noting the feedback is free and doesn't count against tool-call quota. 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 relatively long but every sentence adds essential operational detail. It is front-loaded with the core purpose, then logically flows through when-to-use, exclusions, feedback scope, token usage, team process, rate limit, and cost. No filler or redundant repetition of schema fields.

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

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

For a tool with four parameters, a nested context object, no output schema, and a dual filing/status-checking behavior, the description is remarkably complete. It explains the returned token, how to use it for follow-up, what the team does with feedback, rate limits, and cost implications, leaving no significant operational ambiguity.

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% and each parameter is described, the description adds important semantics beyond the schema. It explains how claim_token is used in context ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), states it should be used 'with no other arguments,' and clarifies that filing returns a token when no account is present. This enriches the structured 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 purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific verb (tell/feedback), the resource (Pipeworx team), and explicitly enumerates use cases (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description gives explicit when-to-use guidance by category (bug, feature/data_gap, praise) and when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' It also explains how to identify Pipeworx tools and mentions rate limits, providing clear selection criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: it is self-aggregated from an analytics engine, contains no PII, returns only (pack, tool, count) tuples, and is cached for 5 minutes to 1 hour depending on window. This goes beyond the annotations.

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

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

The description is well-structured and concise: a clear opening statement, a bulleted list of use cases, and a brief note on aggregation/caching. Every sentence serves a purpose, and it is front-loaded with the core function.

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 sufficient context: it states what is returned (top tools, top packs, total call volume), the output shape ((pack, tool, count)), caching behavior, and data source. An agent can confidently decide when to invoke this tool.

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

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

Schema coverage is 100% for the single 'window' parameter, so the description doesn't need to explain it. The parameter description in the schema already covers the enum and the tradeoff between shorter/longer windows. The tool description reinforces the window choices but adds no new semantic information.

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 what the tool does: it reports what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. It distinguishes itself from siblings like discover_tools by focusing on aggregated usage trends rather than listing available tools.

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

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

The description provides explicit 'Useful for' scenarios, such as discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It does not explicitly name alternatives or when not to use, but the use cases are clear enough for an agent to decide.

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

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

The description goes far beyond annotations by detailing internal logic: monotonicity checks, partition-sum calculations, the Jaccard similarity threshold, the placeholder filter returning null arb signals, and the fill check against CLOB depth with clear 'do not trade' guidance. It adds actionable context about edge cases without contradicting the readOnly/openWorld/idempotent annotations.

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

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

The description is well-organized with front-loaded purpose, distinct mode sections, and labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While it is long, each sentence earns its place by providing examples, thresholds, or response field names, and the structure allows quick skimming for key behavioral 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?

Even without an output schema, the description thoroughly covers return values (opportunities[] fields, partition_check object), handles edge cases (placeholder fraction >20% yielding null signal, negative realizable edge), and provides cross-tool guidance (custom sizing via polymarket_fill_risk). It is entirely self-sufficient for an agent to decide when and how to invoke it.

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

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

Both parameters already have rich schema descriptions, and the tool description adds even more context: full working examples, behavior for each mode (walks child markets, runs comparator on union), and the no-args special case. This fully compensates for the lack of enums or nested objects and explains parameter semantics beyond the schema.

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

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

The description opens with a specific verb-resource-purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three clear modes of operation (trending_scan, event, topic) with concrete examples, and even points to a sibling tool (polymarket_fill_risk) for custom sizing, which helps differentiate it from alternatives.

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

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

Usage guidance is strong: it recommends `event` for a specific market, `topic` for cross-event scanning, and describes the no-args default as a trending scan. It also explains when signals should not be traded (realizable_edge_pp ≤ 0). However, it doesn't explicitly enumerate when to prefer this tool over other sibling arbitrage tools like polymarket_edges or polymarket_kalshi_spread, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description goes far beyond by detailing response structure (by_segment, fed_candidates, _diagnostics), model family logic, edge calculation (net of slippage), Kelly caps, 24h-move warnings, and caching behavior. It also explains why segments can be empty (funnel counters, filter_skips), which is exceptional 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 long and dense, but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). It front-loads the main purpose and uses formatting for scannability. Some details (per-sport α values) could be trimmed, but the complexity justifies much of the length.

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

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

With no output schema, the description fully explains the return structure and semantics: top-level by_segment, fed_candidates with rationale, and _diagnostics with funnel counters and filter_skips. It also explains the model families, edge caveats (e.g., 24h-move warning), and caching. Given the tool's complexity (9 params, no output schema), this is highly complete.

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

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

Schema descriptions already provide 100% coverage, but the tool description adds crucial inter-parameter semantics: e.g., how slippage_pp is subtracted before ranking, why min_kelly never filters partition arbs (because kelly_fraction_half=0 at parent level), and how min_partition_leg_kelly applies per-leg Kelly. This goes well beyond the schema's individual 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself from siblings by framing it as 'what should I bet on today' and describing the consolidated segments (model_driven, structural_arbitrage, concentrated_longshot), separating it from dedicated tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear context for when to use the tool: agents seeking opportunities without paging hundreds of markets, and includes a note on fed candidates explaining why they are excluded. However, it does not explicitly name alternative tools or give direct 'when-not-to-use' guidance, so it falls short of the highest benchmark.

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

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

Annotations already mark read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: snapshot creation on cache-miss, response structure with tracked/expired/snapshot_dates, 60-day TTL limits, and decay computed from daily closes not intraday. This goes far beyond annotations with no contradictions.

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

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

Despite its length, the description is densely informative and structured with ARGS:, RESPONSE:, and LIMITS: sections. Every sentence adds value—no filler. The main answer is front-loaded, and the structured format aids scanning.

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

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

With no output schema, the description fully explains the response fields and their meanings, including edge cases like expired opportunities and snapshot gaps. It also covers limitations (TTL, snapshot availability). For a tool with 2 simple params, this 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?

Schema covers 100% of parameters, so baseline is 3. The description adds clarity by restating defaults (14, '1wk'), clarifying the max for days (30), and explaining window as 'snapshot family' with valid values. This is more than just repetition, 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and the exact question it answers. It differentiates from siblings like polymarket_edges by focusing on time-series behavior rather than current snapshots.

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 context on when to use it via the 'fresh wide edge vs 3-week-old wide edge' example, implying it's for assessing edge longevity. However, it doesn't explicitly name alternatives or state when NOT to use it, but the context is clear enough.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context beyond this: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), treats size_usd differently for buys vs sells, and calls out the dominant loss mode (partial basket fills leaving an unhedged position). 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?

Although long, the description is densely packed and structured with SINGLE-MARKET and BASKET sections, making it scannable. Every sentence carries necessary information—parameters, outputs, risk warnings, and usage timing—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?

With no output schema, the description fully enumerates return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, thin_legs, forced_directional_risk) and includes edge-case warnings. It is complete for an agent to know exactly what the tool returns and what risks to consider.

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%, giving a baseline of 3, but the description goes far beyond the schema: it explains the side default behavior in basket mode (auto based on partition sum), interprets size_usd as settlement notional (shares per leg, paying $1) in basket mode, and documents the clamp range (10–1,000,000). This adds real semantic value for correctly invoking the tool.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as the pre-trade fill-risk validator, and it explicitly names the two modes (single-market and basket).

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk) and describes when to use single-market vs basket mode.

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

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

Annotations already mark readOnly/idempotent/non-destructive; description adds substantial behavioral context: compatibility_warning semantics, temporal_alignment, skipped_cross_type/subtype meanings, spread sign convention (Kalshi − Polymarket), and the caution that most pre-mapped topics return warnings. No contradiction.

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

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

Long and dense, but structured with uppercase labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence carries substantive information. Slightly overlong for a quick scan, but justified by the tool's complexity.

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

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

No output schema, so description carries full responsibility; it covers return structure (leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and failure/limitation semantics. Completeness is high for a complex cross-venue 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 covers all three parameters (100%), and description adds mode behavior (topic auto-fetch vs explicit overrides) and response semantics like top_spreads_pp and compatibility_warning. Baseline 3 plus added usage semantics earns 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?

Description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the tool's function and scope. It distinguishes from likely sibling tools like polymarket_arbitrage by focusing on cross-venue same-question comparison and explicitly naming the normalization/safety conditions.

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 specifies two modes (topic shortcuts vs explicit ticker/slug) and gives concrete examples and exclusion conditions: 'pre-mapped ≠ tradeable' and when compatibility_warning fires. It lacks explicit comparison to sibling tools (e.g., when to choose this over polymarket_arbitrage), but provides clear context and when-not-to-use signals.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavior: returns attribute rows and geometry, plus a sampling pattern. It does not mention rate limits or auth, but for a read-only query tool the added context is sufficient.

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

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

Two concise sentences. Front-loaded with the purpose, followed by a practical usage tip. No wasted words.

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

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

For a query tool with no output schema, the description states what is returned (attribute rows and geometry) and how to source the URL. The tool's simplicity and schema richness make it complete.

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

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

Schema coverage is 100% with detailed descriptions, so baseline is 3. The description lists parameter names but doesn't add meaningful semantics beyond the schema, except for implicitly describing the query functionality.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with a specific verb and resource. It distinguishes from siblings by mentioning the URL comes from search_datasets, making its purpose unambiguous.

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

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

Provides clear context: use the URL from search_datasets and a tip to sample with where='1=1' and out_fields='*'. It lacks explicit when-not-to-use or alternative tools, but the context is definite.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when the key is omitted. The 'without re-deriving it from scratch' clause is rationale rather than a behavioral trait, so a small deduction is warranted.

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: the first states the core action, the second gives usage examples, and the third explains scoping and sibling relationships. Every sentence earns its place with no fluff.

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

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

For a simple tool with one optional parameter, strong safety annotations, and no output schema, the description covers both operational modes (retrieve by key vs. list all keys), scoping, and relationships to remember/forget. It is fully self-sufficient and complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the single key parameter, and the description reinforces the 'omit to list all keys' behavior already in the schema. It adds examples of typical keys ('target ticker, an address, prior research notes') which are helpful context but do not introduce new parameter syntax or 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 opens with a specific verb ('Retrieve') and resource (previously saved value), and clearly distinguishes from siblings by referencing 'remember' and 'forget'. It states exactly what the tool does and how it differs from related tools.

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

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

Explicit use cases are provided ('look up context the agent stored earlier — the user's target ticker, an address, prior research notes'), and the description names alternatives ('Pair with remember to save, forget to delete'). This gives clear when-to-use guidance and differentiates it 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 declare readOnlyHint=true, but the description describes mark_read:true as flagging events read (a side effect that changes future results). This directly contradicts the read-only hint, so the description actually reveals a behavioral trait that clashes with the structured 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 front-loaded with the purpose and uses 4-5 sentences, each adding useful detail. It is slightly verbose in the second sentence but remains efficient overall.

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 and five optional parameters, the description covers return contents, filtering, mark_read semantics, polling safety, and an alternative access method. This is highly complete for the tool's complexity.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds a concrete example type ('sec_8k') and clarifies mark_read behavior, but it does not substantially extend beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' using a specific verb and resource. It clearly focuses on alert retrieval and distinguishes itself from siblings like recent_changes 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 gives explicit usage context: it recommends polling, explains mark_read for incremental reads, and provides an alternative HTTP endpoint for scripts/dashboards, effectively telling when not to use the tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the parallel fan-out to three sources, the fallback logic, the PatentsView API sunset soft-fail, the accepted date formats, and the exact return shape. This is rich behavioral context that annotations do not cover.

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

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

The description is long but every sentence carries unique information: example queries, source enumeration, fallback behavior, parameter details, return format, and an explicit alternative. It's front-loaded with intuitive usage examples, making it dense yet efficient 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?

No output schema exists, so the description compensates by specifying the return structure ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers caveats (PatentsView sunset, GNews fallback) and differentiates from entity_profile, making it self-sufficient for an agent to decide when to invoke.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by recommending a typical value ('Use "30d" or "1m" for typical monitoring'), clarifying the meaning of the 'since' window, and explaining how parameters interact with the sources. It goes beyond the schema's simple 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 it's a change feed for a company over a recent window, with specific verb and resource. It lists concrete example queries and explicitly distinguishes itself from entity_profile ('Use entity_profile instead...'), making it stand out from siblings.

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

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

Provides explicit when-to-use guidance via natural language examples and a clear alternative: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also mentions internal fallback behavior (GDELT→GNews) and the soft-fail for USPTO, which helps set expectations.

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 scoping ('key-value pair scoped by your identifier') and retention rules (24 hours for anonymous, persistent for authenticated). It also clarifies that data is storable across sessions, which is not implied by the annotations. 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 concise and front-loaded. The first sentence states the core purpose, followed by usage context, scoping, and related tools. Every sentence adds useful information 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 simple two-parameter memory write tool, the description covers purpose, usage, persistence, scoping, and related tools. No output schema exists, but the description doesn't need to explain return values for a write operation. It is complete and sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the description adds little beyond what the schema already provides. Both 'key' and 'value' are described in the schema with examples. The description uses examples like 'resolved ticker' to illustrate value types, but this is more contextual than semantic. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (ticker, address, preference). It distinguishes from sibling tools like recall and forget by framing it as the storage side of a paired workflow.

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

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

Provides explicit usage guidance: 'Use when you discover something worth carrying forward' and names alternatives for retrieval and deletion ('Pair with recall... forget to delete'). Also clarifies persistence differences between authenticated and anonymous sessions, helping the 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?

The description adds significant behavioral context beyond the annotations: it cascades lookups, degrades gracefully when external sources are unavailable, labels identifiers with sources, and explicitly lists unresolved identifiers. No annotation contradictions exist.

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 with front-loaded examples, but it is quite long and contains some redundancy (e.g., repeating supported types and input formats). It could be more concise while retaining all essential 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?

Given the tool has no output schema, the description explains the output comprehensively (identifiers, source labels, unresolved list, graceful degradation). It covers the input parameters thoroughly. However, the exact output structure (e.g., JSON format) is not specified, which would make it complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches the schema by providing detailed examples for each parameter (e.g., for 'value': ticker, CIK, ISIN, name for company; brand/generic for drug) and explaining the output context for each type. This adds meaningful 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 resolves a user-spoken name to canonical/official identifiers, supported types (company, drug), and provides example queries. It distinguishes itself as the primary tool to use when you have a name but need an ID, making its purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. However, it does not explicitly mention when not to use this tool or identify sibling alternatives, which would strengthen the guidelines.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description supplements this by explaining that the tool probes each entity with ai_visibility_check, ranks results, and returns additional fields (score, confidence, signal density). This adds context beyond the annotations, though it does not mention potential limitations like rate limits or AI hallucination.

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, followed by the mechanism and use case. Every sentence provides necessary information without redundancy or fluff. It is appropriately concise 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?

Given the tool's complexity (multi-entity comparison, 4 parameters, no output schema), the description covers the key aspects: what it does, how it works (probes with ai_visibility_check), the use case, and the return fields. It does not explain how ranking is computed or the meaning of 'score', but that is partially delegated to the referenced ai_visibility_check. The annotations and schema fill in the remaining safety and parameter details, making it reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of 'entities' with 'your brand + N competitors' and the example query, but it does not add new details about models, _apiKey, or context beyond what the schema already specifies. Thus, it adds some framing but no substantial parameter semantics.

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

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

The description states a specific action ('Compare AI visibility across multiple entities side-by-side') and clearly distinguishes this from the sibling 'ai_visibility_check' by emphasizing the multi-entity comparison and ranking. It also names the output (ranked list with score, confidence, signal density), making the tool's function unambiguous.

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

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

The description provides clear context for when to use the tool ('competitive AI-marketing audits') and gives an illustrative query ('does Claude know about us as well as our competitors?'). It implies the alternative for single-entity checks ('Probes each entity with ai_visibility_check') but does not explicitly state 'use ai_visibility_check for a single entity' or name other alternatives, so it falls short of a full 5.

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

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

With readOnly/idempotent annotations present, the description adds valuable context: fan-out behavior, partial failure degradation, 5-30s latency on first bundlephobia measurement, and the sources_failed reporting mechanism. These details go beyond the structured annotations.

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

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

Dense but efficient: each sentence adds a distinct piece of information (purpose, usage, returns, limitations, failure behavior). Information is front-loaded with the main purpose and flows logically.

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

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

Despite lacking an output schema, the description enumerates the summary block fields, advisory details, links, and alternative versions. It covers ecosystem boundaries and timeout behavior, giving the agent a full operational 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 coverage is 100% with both package and version already described. The tool description adds no further parameter meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check combining deps.dev and bundlephobia. It lists exactly what data sources are used and what the summary includes, distinguishing it from unrelated sibling tools.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear context. It also notes NPM-only in v1 and directs other ecosystems to deps.dev:version directly, serving as a when-not/alternative guide.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds that the tool returns dataset metadata including url, but does not disclose additional behavioral traits like rate limits, pagination, or search matching behavior. With strong annotation coverage, this is adequate but not rich.

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

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

The description is two sentences, front-loaded with the core purpose, lists return fields compactly, and includes a practical instruction on using the result. No wasted words.

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

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

Given no output schema, the description compensates by listing return fields (name, summary, record_count, owner/org, url) and the downstream workflow. The schema covers parameter details. Missing are search behavior nuances like case sensitivity or partial matching, but overall the description is sufficient for an agent to select and invoke the tool.

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

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

The input schema fully covers all three parameters (limit, query, org_id) with descriptions, giving 100% coverage. The description adds minimal extra meaning by mentioning 'by keyword' which maps to query, but does not elaborate on limit or org_id beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches City of Cupertino GIS open geospatial datasets by keyword, with a specific resource (parcels, zoning, public works) and a specific action (search). It distinguishes itself from siblings by explicitly mentioning that the returned URL should be passed to query_layer / layer_info, which are separate tools.

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

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

The description implies when to use this tool: when you need to discover datasets by keyword before accessing data. It points to alternatives (query_layer / layer_info) as the next step, providing a clear workflow. However, it does not explicitly state when not to use this tool or mention alternative search 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 read-only and idempotent, and the description adds substantial technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K cap with truncation flag, and output offsets/scores. This goes well beyond the structured annotations and gives the agent concrete 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?

Three sentences, each carrying distinct value: definition/inputs, usage guidance, and technical mechanics. Front-loaded with the core purpose, no filler, and efficient use of every clause.

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

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

Given the tool's moderate complexity and no output schema, the description fully explains return contents (passages, offsets, scores), usage context, integration with a sibling, and performance boundaries. Nothing essential is left undocumented.

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 enriches semantics with examples of what 'text' means (already-pulled content), query examples, and the 'truncated and flagged' behavior tied to the text field. It doesn't add detail on 'limit' beyond schema but the schema already covers that. This is a solid bonus above baseline.

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

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

The description opens with 'Semantic search INSIDE a fetched record', immediately stating a specific verb and resource scope. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and explaining the niche: searching within already-fetched content rather than the whole document.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt'. It also provides examples of suitable inputs (SEC 10-K, article, long tool result) and pairs with ask_pipeworx_grounded, giving a clear integration alternative. The 200K cap and truncation warning also set boundary conditions.

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

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

Beyond the annotations, the description discloses important behaviors: OAuth requirement, unsupported anonymous/BYO persistence, phone verification, 10/day SMS cap, webhook HMAC signing, one-time secret return, and auto-disabling after 10 consecutive failures. This adds substantial context and does not contradict the annotations.

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

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

The description is dense but every clause contributes context: purpose, auth, types, channels, verification, caps, and webhook edge cases. It is a single long paragraph without formatting aids, and it omits two supported types, but it remains well above minimum viability.

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

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

Given no output schema, the description correctly states the return value (subscription id) and covers auth, required parameters, delivery options, limits, and webhook failure semantics. However, the 'Supported types' list is incomplete (missing patent_grant and clinical_trial), which could mislead an agent choosing a type even though the schema includes them.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples for sec_8k, polymarket_edge, and fred_series params, and by elaborating delivery channel semantics (verified phone, email pattern, webhook restrictions). However, it only details 3 of the 5 types shown in the schema, leaving patent_grant and clinical_trial unexplained in prose.

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

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

The description uses a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the new subscription id. This clearly distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 context on when to use: it requires a Pipeworx OAuth account, notes anonymous/BYO cannot persist, and explains delivery channels plus how to pull alerts via recent_alerts or the registry URL. It does not explicitly mention alternatives like list_subscriptions/unsubscribe for managing subscriptions, so it loses one point.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the output shape (category-bucketed questions with tool+argument shape), the source (live catalog of thousands of tools), and the effect of the optional topic parameter. This provides substantial behavioral context that annotations alone do not.

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 dense paragraph, but it is front-loaded with example queries and quickly establishes the tool's role. Every sentence adds value: examples, purpose, output, and usage. While longer than ideal, the length is justified for an onboarding tool; it remains structured and scannable.

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

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

With no output schema, the description carries full responsibility for conveying the return value, and it does so thoroughly: category-bucketed questions, each with exact tool + argument shape, drawn from a live catalog. It also covers the two invocation modes (no args vs. topic) and when to use it. For a discovery/onboarding tool, this is complete.

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

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

Schema coverage is 100% for the single `topic` parameter, so the baseline is 3. The description adds value by citing concrete examples ('finance', 'pharma', 'betting') and explicitly explaining the default behavior when omitted ('call with no arguments for the full spread'). This enriches the parameter semantics beyond the schema.

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

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

The description clearly states this is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses a specific verb ('suggest', 'returns') and resource ('example questions drawn from the live catalog'), and it is clearly distinguishable from siblings like ask_pipeworx or compare_entities by positioning itself as the 'getting started' tool.

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

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

The description gives explicit guidance: '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 explains the no-argument vs. topic-filtered usage. It stops short of describing when NOT to use certain alternatives, but the context is clear and well-scoped.

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

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

The description adds context beyond the annotations: ownership is enforced and the row is deactivated not deleted, keeping historical events available. This aligns with destructiveHint=false and 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?

Two sentences, front-loaded with the action, and zero wasted words. It states purpose, constraint, and effect efficiently.

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

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

For a single-parameter mutation with no output schema, the description covers the essential behavioral aspects: ownership, soft-delete, and how to access historical events. It doesn't mention return values, but the simplicity and annotations make it sufficient.

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

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

Schema coverage is 100% and the description adds no additional parameter details beyond what the schema already provides (id is a uuid from subscribe). 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 uses the specific verb 'Cancel' and identifies the resource as a 'subscription' by id, clearly distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

It explicitly states ownership enforcement (only your own subscriptions) and explains the deactivation effect, referencing recent_alerts as an alternative for historical events. While it doesn't list exclusions, the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context: the two internal routing paths, the meaning of each verdict, and the crucial distinction between could_not_verify (check did not happen) and unsupported (no source exists). This goes well beyond what annotations alone 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?

Though long, the description is dense and front-loaded: trigger phrases, purpose, usage context, internal behavior, return values, and critical caveats follow a logical order. Every sentence earns its place, and the closing 'Replaces 4–6 sequential calls' succinctly captures efficiency.

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

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

With no output schema, the description fully explains return verdicts, evidence citation, and reasoning. It also covers both internal pipelines and error semantics (verification_error), making it self-sufficient for an agent to correctly interpret results and know what to communicate to the user.

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 already-detailed descriptions for both parameters (claim example and tolerance_pct semantics). The description adds minimal new parameter meaning, only reinforcing the 'exact percent-delta math' concept, so the baseline 3 applies.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes the tool from generic Q&A by specifying the two internal paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else) and notes it replaces 4–6 sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It also contrasts with multi-step pipelines by noting it 'Replaces 4–6 sequential calls.' However, it doesn't name sibling tools or provide explicit when-not-to-use exclusions.

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