Arcgis Grandchute

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, so the bar is lower. The description adds meaningful context: default model is free (Workers AI), passing _apiKey sends calls to Anthropic and incur costs for the user, and return per-model includes signals/raw_response.

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

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

Three sentences with no fluff: purpose, model options, return format, and use cases. Information is front-loaded and every sentence earns its place.

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

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

No output schema exists, but the description enumerates the return values ({score, confidence, signals, raw_response} + combined view) and covers key invocation details (required entity, optional models, API key conditionality). Complete for agent decision-making.

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, but the description goes further: it explains the default model, clarifies that _apiKey is only for Anthropic, and highlights that context disambiguates common names. This adds 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 uses a specific verb ('probe') and resource ('LLMs') and clearly states the outcome: score visibility (0-100) per model. It distinguishes from siblings like ask_pipeworx by focusing on multi-model visibility scoring and returning a combined view.

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

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

The description provides clear usage contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional _apiKey param, but does not explicitly mention when not to use the tool or suggest alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety is covered. The description adds behavioral context not in annotations: routing across 5,462 tools, returning stable citation URIs, 'one fast call', and 'works on every tier'. It also notes that it can handle breaking news and live data. 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 longer than average but well-structured, front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'), followed by what it does, when to use, examples, and alternatives. Every sentence adds value, and the length is justified for a default entry point tool.

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

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

Without an output schema, the description explains the return value ('structured answer with stable pipeworx:// citation URIs') and covers the tool's role as default entry point. It mentions limitations and alternatives. It could delve into outputs for specific domains, but given the tool's breadth, the description is appropriately complete.

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

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

Schema coverage is 100% with a clear description for the 'question' parameter and aliases. The description adds examples of valid queries, but these are more about usage than parameter semantics. The schema already provides sufficient parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes questions to authoritative tools and returns structured answers with citation URIs. It explicitly lists covered domains (SEC, FDA, FRED, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research. The verb 'routes' and resource '5,462 tools' provide a specific, actionable 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 explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', includes trigger phrases and concrete examples. It also states when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. This is textbook usage guidance.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds crucial behavioral context: live candidate routing improvements may be enabled, the current inactive state with a specific date, and that it is a full working router with no fallback. These go 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?

Three dense sentences, front-loaded with 'Beta version', and zero fluff. Every statement earns its place: identity, current status, usage, and comparison behavior.

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

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

No output schema exists, but the description says 'same response shape' as ask_pipeworx, borrowing necessary context from the stable sibling. It also covers current experimental status and the comparison role. Slightly more detail on routing improvement behavior would be nice, but it is 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%—all six parameters are aliases with descriptions. The description adds no parameter-specific meaning beyond saying 'same arguments' as ask_pipeworx, so the schema carries the burden and the 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 it is a beta version of ask_pipeworx, a universal router with the same 5,462 tools, arguments, and response shape. It distinguishes itself from the stable sibling by its experimental nature and live routing improvements.

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 it exactly like ask_pipeworx when you want the newest routing', and notes that it currently matches ask_pipeworx exactly when no candidate is active. This gives clear when-to-use guidance and implies the stable ask_pipeworx as the alternative.

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

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

Adds significant behavioral context beyond the annotations: the refusal reasons (not_in_source, no_tool_match, etc.), the return shape with evidence and confidence, the extra LLM call cost, and the grounding constraint. This is complementary to the annotations (readOnly, openWorld, idempotent) with no contradiction.

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

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

Every sentence carries functional weight: definition, mechanism, return format, usage triggers, and cost trade-off. It is front-loaded with the core value proposition and well-structured, making it dense but appropriately sized for the tool's complexity.

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

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

With no output schema, the description takes on the full burden of explaining return values, and it does so thoroughly by detailing both success and explicit refusal response objects. Coverage of cost, alternative, and safety context makes the description complete 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 has 100% coverage with clear descriptions for all six aliases, so the schema already documents the parameters. The description mentions that the tool 'fills arguments' but does not add parameter-level detail beyond the schema, earning the baseline 3 for schema-heavy documentation.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating a specific verb+resource purpose. It distinguishes itself from the sibling ask_pipeworx by emphasizing the extraction of answers using only tool results and the explicit refusal mechanism.

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

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

Explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ask_pipeworx for casual lookups due to the extra LLM call cost. This provides clear usage direction and sibling differentiation.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond annotations: parallel fan-out, resolver contract with market_match_confidence, parent_event extractor, GDELT fallback mechanics, low-confidence short-circuit behavior, closed-market status, wide-spread liquidity warning, and cancellation-rule parsing. This is rich, non-contradictory context.

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

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

The description is long but highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It is front-loaded with the core purpose and use cases. Some repetition and density could be trimmed, but the complexity of the tool justifies 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?

There is no output schema, so the description takes on the burden of explaining return shapes—which it does thoroughly via response shape annotations, resolver contract details, parent_event fields, news failure flags, and status codes. It also covers edge cases like low-confidence matches, closed markets, and wide spreads, making it complete for a complex tool.

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

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

Schema description coverage is 100%, with clear descriptions for market, depth, and include_raw. The tool description largely reinforces this without adding much new semantic detail for parameters—though it gives examples and elaborates on include_raw's size implications. This meets the baseline for fully documented schema but does not substantially exceed it.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on evidence aggregation and market-vs-model comparison for a single bet.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes concrete fan-out examples for many bet types. However, it does not explicitly name alternative tools to use instead or state when not to use this tool, leaving a small gap.

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

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

The description discloses significant behavioral details beyond the read-only annotation: it specifies the exact data pulled (LATEST 10-K revenue, net income, cash, long-term debt for companies; FAERS adverse-event counts, FDA approval counts, active trial counts for drugs), mentions correct handling of off-calendar fiscal years, explains sorting by primary metric, and notes the return format (paired data + citation URIs). This far exceeds what annotations alone provide.

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

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

The description is compact yet information-dense, using example phrases and semicolons to front-load key behavior. Every sentence earns its place, covering purpose, usage guidance, data specifics, sorting, and return format without redundancy. Despite its length, it is well-structured and efficient.

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

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

Given the tool's moderate complexity, the description covers all necessary context: what it does, when to use it, what data it retrieves, how results are ordered, and what output to expect (paired data + citation URIs). Even without an output schema, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Although the schema already documents both parameters with 100% coverage, the description adds meaning by explaining how 'type' affects data retrieval (company vs drug) and giving concrete examples for 'values' (tickers/CIKs vs drug names). It also reinforces constraints like 2–5 items, enriching the schema's bare 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 a specific verb and resource: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also provides example phrasings ('Compare X and Y', 'X vs Y', 'which is bigger') that anchor the tool's purpose. This distinguishes it from sibling tools like entity_profile, which likely handles single-entity lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving direct guidance on when to use this tool versus alternatives. It also clarifies the entity types (company/drug) and the data sources, making the use case unambiguous.

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

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

Annotations declare readOnly/openWorld/idempotent hints, but the description adds substantial behavioral context beyond them: parallel decomposition into facets, gap recovery behavior per depth tier, contradictions[] scan, semantic excerpting (not head-truncation), expected latency (15-60s, up to ~90s), citation_uri resolvability guarantee, and account/plan requirements. It also clarifies what happens when data is missing (never invented, gaps[] returned). This fully discloses the tool's behavioral traits 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?

The description is long but every sentence earns its place: it covers purpose, alternatives, exclusions, parameter semantics, latency, citations, and failure behavior. It front-loads the most critical operational detail (account requirement and sign-in) and progressively adds depth. It is dense rather than verbose, though slightly over-stuffed; a minor trim of the citation details could improve scannability without losing value.

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

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

The tool is complex with multiple depth tiers, external dependencies (account plans), and nuanced failure modes. The description covers all key aspects: prerequisites (account), alternatives, expected latency, return findings structure (verbatim evidence, confidence, source, fetched_at, citation, gaps, contradictions), and limitations. With a comprehensive schema and annotations, the description completes the picture comprehensively—no significant gaps remain for an agent to confidently 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?

While schema coverage is 100%, the description adds meaning beyond the enum labels: it explains what each depth tier does procedurally ('quick=3 (single hop)', 'standard=5... adds a gap-recovery hop... contradictions[]', 'thorough=8 (paid)... chases leads + recovers gaps') and clarifies that broad/multi-part questions are fine for the question parameter ('decomposition is the point'). This goes beyond the schema's bare enum/type descriptions, enhancing the agent's ability to choose parameter values.

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

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

The description opens with a specific verb+resource: grounded multi-source research over Pipeworx's 1419 structured data sources, explicitly distinguishing it from open-web search. It clearly names sibling alternatives (ask_pipeworx, bet_research, compare_entities) and states it is NOT open-web search, which removes ambiguity. The examples ('compare X and Y's regulatory + financial exposure') anchor the intended use case, making the tool's 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It even explains why deep_research fails for news topics (returns mostly empty gaps[]) and notes that depth:'thorough' requires a paid plan. This is exemplary usage guidance with named alternatives and concrete exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details beyond annotations: it returns top-N tools with names, descriptions, full input schemas, and curated examples, and states that results are ready to call directly with no second schema lookup. This gives the agent a clear model of the tool's output and behavior without conflicting 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 with the core purpose. It packs actionable usage guidance, domain examples, and return-value details into a few sentences without redundancy or filler. Every sentence earns its place, making it highly scannable for an AI agent.

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

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

Despite no output schema, the description fully explains what the tool returns (top-N tools with schemas and examples) and how to use it. It covers the main usage scenario (discovery when many tools exist), and the annotations handle safety. The tool is simple enough that this level of description is complete 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 adds some context by framing the query as a natural language description of a task and listing example domains, but it does not significantly extend the schema's parameter descriptions. The aliases (q, task, search, description) are already documented in the schema, so the description adds marginal value here.

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 phrase 'Find tools by describing the data or task' and clearly identifies the resource (tools) and purpose (discovery). It distinguishes itself from sibling tools by framing itself as a meta-tool for browsing/selecting other tools, with explicit domain examples and a directive to call it first.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and implies when not to use (when you already know the specific tool), differentiating it from direct data-query siblings.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds rich behavioral context beyond that: it fans out across multiple sources, returns up to 5 filings, sorts fundamentals by period_end DESC, soft-fails on the USPTO PatentsView API sunset, and uses a GDELT→GNews fallback for news. These details disclose limits, failure modes, and fallback behavior that the annotations do not convey.

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

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

The description is long but every sentence earns its place: the query examples establish use cases, the core purpose is stated in one clear clause, usage preference is explicit, and the parallel data sources and return fields are enumerated precisely. There is no filler or tautology; the density is justified by the tool's complexity.

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

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

With no output schema, the description must explain the return structure, and it does so thoroughly: it lists cik + company_name, recent_filings with URI format, fundamentals with specific financial items and sorting, patents with sunset caveat, news with fallback, and LEI. It also covers input constraints, source fan-out, and usage guidance. This is complete enough for an agent to correctly invoke the tool and interpret its results.

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

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

Schema description coverage is 100%, with both 'type' and 'value' fully described in the input schema. The description adds example formats ('AAPL', '0000320193') and reinforces that names are not supported, but it largely repeats the schema's parameter documentation. The additional examples are marginally useful but do not significantly extend the semantic meaning beyond the structured schema, so the baseline of 3 is appropriate.

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

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

The description opens with multiple concrete query examples ('Tell me about X', 'brief me on Tesla', etc.) that clearly illustrate the tool's intent, then defines it precisely as a 'full cross-source profile of a US public company in ONE parallel call'. It explicitly differentiates itself from 'chaining single-pack SEC/XBRL/news lookups' and lists the exact data domains (SEC, XBRL, USPTO, news, GLEIF), making the purpose unmistakable and distinct from siblings like compare_entities or deep_research.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion and alternative: 'names not supported (use resolve_entity first if you only have a name).' This tells the agent exactly when this tool is appropriate and when to delegate to a sibling.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is known. The description adds context about clearing sensitive data but does not disclose additional behavioral details (e.g., permanence, error behavior) beyond what annotations provide.

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

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

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

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

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

The tool is simple (1 required param, no output schema) and the description covers what it does, when to use it, and how it relates to siblings. It might optionally mention the result of deletion, but given the annotations and simplicity, it is sufficiently complete.

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

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

Schema coverage is 100% with the parameter 'key' explicitly described as 'Memory key to delete'. The description only says 'by key', adding no further meaning beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource, and it distinguishes from sibling tools by referencing 'remember' and 'recall' as complementary operations. It is unambiguous and specific.

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

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

The description explicitly gives three use cases ('context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with 'remember' and 'recall'. It lacks explicit when-not-to-use guidance but is clear enough for a simple delete operation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations by describing what the tool actually does with the URL and the output format.

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

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

The description is four sentences, each serving a clear purpose: what it does, how it works, what the output is, and when to use it. It is front-loaded with the primary function and contains no redundant or filler content.

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

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

The tool has no output schema, but the description explicitly states the output is 'a single text blob ready to drop at site-root/llms.txt' and mentions the standard markdown format. It covers use cases and behavior. Minor gaps like failure handling or edge cases (e.g., URL fetching errors) are not addressed, but for this simple tool the description is 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 schema fully documents 'url' and 'max_links'. The description does not add any additional parameter semantics beyond what the schema already provides (e.g., no extra context on how max_links affects the output). 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 what the tool does: generate a production-ready llms.txt file for a URL. It specifies the resource (llms.txt file) and the verb (generate), and distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on the specific llms.txt output rather than general AI presence scanning.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') and the general context ('any URL'). However, it does not mention alternatives or when not to use it, which would elevate it to 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 the tool as readOnly, idempotent, and non-destructive, so the bar is lower. The description adds value by specifying the return content (schema, fields, geometry, count, capabilities) but does not mention error handling, URL validation, or other behavioral details. It 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 a single, front-loaded sentence that conveys the tool's function and output list with no wasted words. It is efficiently structured and immediately actionable.

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

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

For a simple read-only tool with one well-documented parameter and no output schema, the description covers the essential details: what the tool does and what it returns. It could mention that it is safe/read-only, but the annotations already cover that, making the description sufficiently complete.

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

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

The input schema provides 100% coverage for the single 'url' parameter, explaining it is a Feature/Map Service layer URL with an example. The description merely says 'by url' without adding additional syntax or format details, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool gets an ArcGIS Feature/Map Service layer's schema and enumerates the specific data returned (fields, geometry type, record count, capabilities). This is a specific verb+resource combination, though it does not explicitly differentiate from sibling tools like query_layer, so it falls short of a 5.

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?

No guidance is provided on when to use this tool versus alternatives such as query_layer or search_within. The description implies usage when needing schema information, but it lacks explicit context, 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 establish the operation as read-only, idempotent, and non-destructive. The description adds valuable context by specifying the exact return structure (id, type, params, created_at, last_fired_at, fire_count) and clarifying that it returns only the caller's active subscriptions by default. This goes beyond the annotations, though it doesn't address potential limitations or side effects (none evident for a read-only list).

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 well-structured: it opens with the core action, then lists the return fields, and closes with usage guidance. Each sentence serves a distinct purpose with no unnecessary elaboration, making it easy for an agent to parse quickly.

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

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

For a simple read-only list tool with one optional parameter (fully documented in the schema) and no output schema, the description provides all necessary context: what it does, what it returns, and when to use it. The annotations cover the safety profile, so there are no significant gaps.

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

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

The input schema has 100% coverage for the single optional parameter (include_inactive) with a clear description. The tool description does not mention this parameter explicitly, so it adds no additional semantics. However, since the schema fully documents the parameter, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It uses a specific verb ('list') and resource ('subscriptions'), specifies the scope ('caller's active'), and differentiates from sibling tools like subscribe/unsubscribe by positioning itself as a review step. The return fields are enumerated, leaving no ambiguity about what the tool does.

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

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

The description provides explicit usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool. However, it does not explicitly name alternatives (e.g., subscribe/unsubscribe) or state when not to use it, so it falls short of full when/when-not guidance.

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

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

The description goes well beyond annotations by disclosing the claim_token mechanism, rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and operational traits (team reads digests daily, signal affects roadmap). It also explains what to include and what not to include (don't paste the end-user's prompt). All annotations are false, so there is no contradiction and the description carries the full burden—which it meets.

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 notably longer than average (about 150 words), but every sentence provides unique, actionable information—usage cases, exclusions, feedback composition guidelines, token behavior, rate limits, and cost. It is front-loaded with the core purpose and structured logically. While not as terse as a two-sentence description, it earns its length through density of useful guidance.

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

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

For a tool with no output schema, the description sufficiently explains the key return behavior (claim_token and how to use it later). It also covers prerequisites (no account needed to file), constraints (rate limit, free), and process (team reads digests daily). Given the tool's moderate complexity and the richness of the schema/annotations, the description leaves no significant gaps for an agent to invoke it correctly.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds extra value by giving a concrete usage example for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' This clarifies the parameter's purpose beyond the schema. It also reinforces the message parameter's intended content, but the schema already does this well.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team/connection) and the purpose (submitting feedback). It also distinguishes itself from sibling tools by emphasizing it is only for tools served by this Pipeworx connection and explaining what type of issues belong here (bugs, features, data gaps, praise).

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

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

The description provides explicit use cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: 'if the tool came from a different MCP server in your client... we cannot fix it and reporting it here only delays you; file it with that server instead.' This fully covers when to use vs not use.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses meaningful behavioral details: it is 'derived from CF analytics-engine,' includes 'no PII, just (pack, tool, count),' and is 'Cached 5min-1h depending on window.' These details inform the agent about data freshness, privacy, and internal source, adding substantial value over the annotations alone.

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

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

The description is moderately sized but extremely well-structured: it opens with the primary output, lists three numbered use cases, and ends with technical caveats (caching, PII, data source). Every sentence contributes distinct information, though it is slightly verbose compared to minimal two-sentence examples.

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 and no output schema, the description adequately covers what is returned (top tools, top packs, total call volume), the meaning of windows, and the data scope. It does not provide a sample response or sort order, but the '(pack, tool, count)' detail is enough for an agent to understand the response shape.

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

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

The schema already covers the single 'window' parameter with an enum and description (100% coverage). The description adds interpretive guidance—'Shorter windows surface what's hot right now; longer windows show steady-state demand'—which clarifies the semantic difference between options beyond the raw schema.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource pairing and distinguishes it from siblings like discover_tools by focusing on aggregated call-volume trends rather than tool discovery.

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

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

The description provides three explicit use cases ('Useful for...') that explain when to apply the tool, such as discovering hot data sources or confirming a canonical tool choice. It does not name specific alternatives for exclusion, but the context is sufficient for an agent to decide when this tool fits.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses algorithmic details: threshold values (>3pp, Jaccard ≥0.30, placeholder >20%), the fill-check warning ('realizable_edge_pp ≤ 0 ... do not trade it'), and the exact response shape. This goes far beyond the annotation hints.

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

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

The description is long but well-structured with clear mode breakdowns and capitalized sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). However, the FILL CHECK section is nested inside the event-mode explanation, and the overall length is near the upper bound of what remains digestible.

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

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

Given no output schema, the description fully documents return values (opportunities[], partition_check fields) and even covers edge-case behavior like thin_legs and the 'do not trade' instruction. It also explains the semantic similarity threshold and placeholder filtering, making it complete for a complex tool.

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

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

The input schema already fully documents both parameters (100% coverage), but the description adds substantial meaning: concrete slug examples ('fed-decision-may-2026'), behavioral differences between event and topic modes (walks child markets vs flattens the union), and internal checks (date-axis/threshold-axis ordering).

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

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

The description opens with a specific action and method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges by focusing on arbitrage, and the three modes (trending, event, topic) further define its scope.

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

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

It provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also recommends a mode for specific markets and references an alternative tool: 'For custom sizing use polymarket_fill_risk.'

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 readOnlyHint/openWorldHint/idempotentHints, the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), output structure ('by_segment{model_driven,structural_arbitrage,concentrated_longshot}'), diagnostics for empty segments, and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). This is rich behavioral context.

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

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

The description is appropriately front-loaded and uses headers for readability, but it is extremely long and dense, with many parentheticals and detailed sub-explanations. While each sentence adds some value, it could be trimmed without losing essential guidance.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly details the top-level response structure (by_segment, fed_candidates, _diagnostics), the logic behind each segment, and the meaning of each field. This is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by grouping knobs (TRADEABLE-EDGE KNOBS) and explaining subtle interactions like min_partition_leg_kelly applying to per-leg Kelly because 'partition arbs always return kelly_fraction_half=0 at the parent level by design.' This goes beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames the use case ('what should I bet on today') and distinguishes itself from sibling tools by focusing on opportunity discovery without paging hundreds of markets.

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

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

The description provides clear context for use ('Built for what should I bet on today') and explains exclusions, e.g., 'Fed bets surface here, excluded from ranking.' It also details when to apply tradeable-edge knobs. No explicit alternatives to sibling tools are named, but the context is unmistakable.

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

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

Even though annotations already declare read-only and idempotent behavior, the description goes far beyond by explaining snapshot write triggers (cache-miss), implications of gaps (nobody scanned that day), the 60-day TTL bound, and that decay is computed from daily closes rather than intraday. It also explains the sign convention for edge_pp_net (negative = SELL YES). This adds substantial behavioral context with no contradiction.

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

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

The description is well-structured with clear labels (Args, RESPONSE, LIMITS) and is information-dense. However, it is somewhat verbose, with conversational asides like 'the latter is wide for a reason nobody is willing to take' that add flavor but could be trimmed. Overall, every section serves a purpose and the organization is excellent.

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 takes full responsibility for explaining the return format, and it does so comprehensively: tracked[], expired[], snapshot_dates[] with field-level detail. It also covers historical limits and data granularity. For a tool of this complexity, the description is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the 'days' parameter's max 30 (schema says clamp 2-30) and 'window' as a snapshot family selector. More importantly, it explains how these parameters affect the response (days lookback, window selects which family's snapshots), and the response description ties them to actual data availability.

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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers the core question 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges by focusing on temporal behavior rather than current edges.

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

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

The description provides strong contextual guidance by framing the tool as the way to differentiate fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or state 'use this instead of X', but the implied use case is clear. The LIMITS section also clarifies when historical depth is constrained, adding practical usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond that. It details the order-walking algorithm, return metrics, the meaning of size_usd in each mode, and the risk of partial basket fills converting an arb into an unhedged directional position. This far exceeds the annotation baseline and provides critical safety information.

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

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

The description is long but densely structured. It front-loads the core purpose, then organizes content into single-market vs basket modes, lists outputs, and closes with explicit usage guidance. While it is more verbose than a typical description, every segment serves a purpose for a complex tool. It could be tightened, but the structure (bold markers for modes and terms) aids comprehension.

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

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

The tool has no output schema, so the description must explain return values. It does thoroughly: for single-market it lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and verdict; for basket it lists theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also explains the broader context of why this tool exists (partial basket fills are the dominant loss mode). The description is fully self-sufficient for an agent to understand behavior and outputs.

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. However, the description significantly enriches the schema's parameter descriptions. It clarifies that `market` means single-market mode, `event` means basket mode, `side` has mode-specific defaults (e.g., "default auto — sell if partition sum > 1, buy if < 1"), and `size_usd` is interpreted differently in single-market (spend/proceeds) vs basket (settlement notional, shares per leg). This added semantics goes well beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb+resource: "Realizable-vs-theoretical edge check against live CLOB order-book depth." It clearly distinguishes two modes (single-market and basket/partition) and explicitly differentiates from sibling tools by stating "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500."

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

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

It provides explicit when-to-use guidance: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500". It also specifies mode selection requirements: "REQUIRES one of `market` (single-market mode) or `event` (basket/partition mode)", including default behaviors. While it does not list exclusions, the threshold and signal context are 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?

Despite annotations already declaring readOnly and idempotent behavior, the description adds substantial behavioral context: compatibility_warning conditions (matched_pairs:0 cases), temporal_alignment semantics, skipped_cross_type/subtype counters, and the explicit disclaimer that pre-mapped ≠ tradeable. It thoroughly explains what the tool does when comparisons fail or are meaningless, going well beyond annotation hints.

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

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

The description is long but highly structured with clear markers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries meaningful information—there is no fluff. The front-loaded core definition ('Cross-venue spread...') and pragmatic warning about tradeability make it efficient for an AI agent to parse.

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

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

With no output schema, the description fully bears the burden of explaining return values and edge cases. It covers leg-by-leg prices, matched spread/top_spreads_pp, compatibility_warning scenarios, temporal alignment, and skipped cross-type/subtype counters. It even clarifies when spreads are mathematically meaningless. This is a complete picture for a complex cross-venue comparison tool.

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

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

The input schema already covers 100% of parameters with descriptions and examples, providing a baseline of 3. The description adds value by clarifying the two-mode interaction (topic vs explicit tickers, with explicit tickers overriding topic-mapped sides) and explaining how the topic shortcuts auto-fetch matching events. This contextualizes parameters beyond the schema's individual field descriptions.

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

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

The description clearly states the tool's core function: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by specifying the two venues and enumerating both operating modes (topic shortcuts and explicit tickers). The verb 'spread' and resource definition are precise and unambiguous.

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

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

The description explains when to use the tool via two modes (topic shortcuts vs explicit tickers) and provides context on when the output is meaningful (bet shapes equivalent vs not). It warns that most pre-mapped topics return compatibility warnings, implying tradeable spreads are rare. However, it does not explicitly reference sibling alternatives or state 'use this instead of X', slightly reducing the score from 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 read-only/idempotent behavior. The description adds value by disclosing that the tool returns attribute rows and geometry, and by clarifying the SQL-like query semantics. 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?

Two sentences with no wasted words. The first sentence immediately states the tool's purpose and source, and the second provides a useful sampling example. Perfectly front-loaded and compact.

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 adequately explains return values (attribute rows and geometry) and provides enough context to select and invoke the tool. It does not cover error cases or full result formatting, but for a read-only query tool with rich schema annotations, this is sufficient.

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

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

The input schema already provides 100% coverage for all parameters. The description summarizes the parameter list (where, out_fields, order_by, limit, offset) but adds little beyond the schema. It does add context about SQL-like syntax and returning geometry, keeping it at 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 has a specific verb ('Query'), a clear resource ('ArcGIS Feature Service / Map Service layer'), and contextual linkage ('by its url (from search_datasets)'). This clearly distinguishes it from sibling tools like search_datasets or layer_info.

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

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

The description clearly indicates when to use the tool (after search_datasets) and provides practical guidance (e.g., using where="1=1" + out_fields="*" to sample). It does not explicitly mention alternatives or exclusions, but the usage 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context about scoping ('anonymous IP, BYO key hash, or account ID') and the dual behavior (retrieve one key vs. list all). This goes beyond what annotations provide, though it does not detail edge cases like missing keys.

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

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

Three sentences, each earning its place: purpose and behavior, usage context with concrete examples, and scope plus pairing. Information is front-loaded and there is no fluff or repetition of schema/annotation details.

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

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

For a low-complexity tool with a single optional parameter, the description is fully self-sufficient. It explains the two modes, scoping, and how it relates to sibling tools (remember/forget). No output schema is present, but for a read-only lookup the return format is self-evident; the omission does not create 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?

Schema coverage is 100% (the key parameter is fully described, including the omit-to-list-all behavior). The description reinforces this and adds real-world examples of what keys might contain (ticker, address, research notes), which helps the agent understand what values are meaningful to store and retrieve. This additional context earns a score above 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 opens with a specific verb ('Retrieve') and a clear resource ('a value previously saved via remember'), and immediately distinguishes itself from sibling tools by also covering the list-all behavior. It names remember and forget explicitly, making the tool's role in the memory triad unmistakable.

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

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

It clearly states when to use this tool ('Use to look up context the agent stored earlier') and provides practical examples (target ticker, address, research notes). It also gives pairing guidance with remember and forget. It does not explicitly mention when *not* to use it or enumerate alternative tools, but the intent is unambiguous.

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

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

Annotations already mark it read-only/idempotent; description adds value by disclosing the mark_read side effect and that the same feed is available via GET. This goes beyond the safety profile 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?

Four sentences, front-loaded with purpose, each sentence adds value: return data, filtering, mark_read, alternative endpoint. No wasteful 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?

Covers main aspects: return fields, filtering, side-effect behavior, and alternative access. Minor gaps like interplay between unread_only and mark_read but overall complete for a read-heavy tool.

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

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

Schema description coverage is 100%, so parameters are already documented. Description adds an example filter type but does not significantly enhance understanding beyond 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?

Description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the resource and action, distinguishing it from siblings like list_subscriptions or recent_changes.

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?

Gives context on when to use it (polls work fine, alternative HTTP endpoint) and how to filter, but does not explicitly exclude alternative tools. It clearly implies usage for polling alerts.

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, idempotent, non-destructive), the description discloses rich behavioral details: it fans out to SEC EDGAR, GDELT→GNews fallback with specific failure conditions, USPTO patents with PatentsView sunset causing soft-fail, and returns structured changes with citations. This goes far beyond the annotation hints and fully discloses data sources and failure modes.

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

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

The description is dense but well-organized, leading with natural language examples, then the core function, then details on sources and 'since' format, and ending with an alternative tool. While long, every clause carries essential information for a multi-fallback tool; no filler or 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?

Despite no output schema, the description clearly states the return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers source fallbacks, failure modes, time formats, and the alternative tool. Given the tool's complexity, this description 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%, so the baseline is 3. The description's mention of 'since' accepting ISO dates or relative shorthand and 'value' as ticker/CIK does not add meaning beyond what the input schema already states. No additional parameter semantics are provided beyond schema descriptions.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, using phrases like 'change feed for a company in the last N days/weeks/months' and 'What's new with X'. It also distinguishes from sibling entity_profile by explicitly stating 'Use entity_profile instead when you want the static profile...', providing clear differentiation.

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 handles temporal queries like 'latest on Y' or 'updates on Acme', and provides an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also explains when the tool is preferred over siblings (dynamic change feed vs. static profile).

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

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

The description adds valuable behavioral context beyond the annotations: storage scoping by agent identifier, persistence differences between authenticated and anonymous sessions, and a 24-hour retention limit for anonymous sessions. This directly explains the tool's storage and lifecycle behavior, complementing the idempotentHint annotation without contradiction.

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

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

The description is compact and front-loaded with the core purpose. Every sentence earns its place: purpose, usage trigger, storage model, retention details, and sibling references. It avoids redundant restatement of the title and maintains high information density without verbosity.

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

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

For a simple two-parameter write tool, the description is complete: it covers when to use it, how the data is stored, how long it persists, and how it connects to recall and forget. There is no output schema, but the return value is unimportant for a store operation, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that this is a 'key-value pair scoped by your identifier', but it does not meaningfully enrich the parameter meanings beyond the schema's own examples. The schema adequately documents key and value, and the description doesn't add constraints or nuance.

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

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

The description states a specific verb-resource pair ('Save data ... key-value pair') and clearly distinguishes it from sibling tools by naming 'recall' and 'forget' as complementary operations. It also provides concrete examples of what to save, making the tool's 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?

Explicitly says 'Use when you discover something worth carrying forward' and gives contextual examples (ticker, address, preference, subject). It also tells when to use related tools ('Pair with recall to retrieve later, forget to delete'), which serves as a when-not-to-use-remember guideline.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by specifying return values (ticker, CIK, company_name, RxCUI, ingredient, brand), data sources (SEC EDGAR, RxNorm), citation URIs, auto-disambiguation, and internal cascading lookups. This enriches the agent's understanding of what happens during execution.

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

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

The description is moderately long but well-structured, with example queries, a clear directive, and a breakdown of supported types. It is front-loaded with the core purpose and every sentence contributes value, though it could be slightly tightened without losing meaning.

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

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

With no output schema, the description adequately explains return values, data sources, and citation URIs. It covers the main use cases and input formats for both entity types. It doesn't address failure modes (e.g., entity not found), but for a lookup tool with robust annotations, this is a minor gap and the overall context is complete enough for effective use.

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

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

Schema description coverage is 100%: both parameters are described with detailed examples and enums. The description mostly repeats schema info (e.g., ticker/CIK/name for company, brand/generic for drug) and adds little new semantic detail. It does mention auto-disambiguation and citation URIs, but these are more behavioral than parameter-specific, so the baseline score of 3 applies.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, RxCUI) and supported types (company, drug). It uses a specific verb 'resolve' and distinguishes itself from sibling tools by focusing on the name-to-ID use case that other tools likely depend on.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This is a clear context for when to use the tool. However, it doesn't mention when not to use it or explicitly name alternative tools, so it lacks full exclusions but is still clear for most scenarios.

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

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

The description discloses internal behavior beyond the annotations: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds meaningful context about the tool's workflow and output, complementing the readOnlyHint and idempotentHint annotations.

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

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

The description is three focused sentences that front-load the core function, then add use case and output details. Every sentence earns its place with no redundancy or fluff.

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

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

For a multi-entity comparison tool with no output schema, the description adequately covers input (entities, models, context), process (probing, ranking), output (ranked list with score/confidence/signal density), and typical use case. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add substantial meaning beyond the schema; it echoes the concept of 'your brand + N competitors' but the schema already explains that the first entity is the subject. No extra parameter semantics are provided.

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: comparing AI visibility across multiple entities side-by-side. It specifies the verb 'Compare', the resource ('AI visibility'), and distinguishes itself from siblings like ai_visibility_check by focusing on multi-entity comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use this tool versus the single-entity sibling ai_visibility_check ('Probes each entity ... with ai_visibility_check'). However, it does not explicitly state when NOT to use it or mention alternatives for non-competitive scenarios.

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

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

Beyond the readOnly and idempotent hints, the description discloses composite behavior, partial failure handling, timeout behavior (5-30s), and the sources_failed field. This adds significant context that annotations don't convey.

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

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

The description is dense but every sentence adds value: purpose, usage, return fields, ecosystem constraint, and failure behavior. It is well-structured and front-loaded, 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?

The tool is complex (composite across two services, no output schema) yet the description covers return fields, failure modes, timing, and alternatives. This provides sufficient context for an agent to use it correctly without needing an output schema.

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

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

Schema coverage is 100%; both parameters are already well-described in the schema (e.g., scoped packages accepted, version defaults to latest). The description does not add extra parameter semantics beyond repeating these details, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'Composite "should I add this npm package to my project" check in ONE call' that fans out across deps.dev and bundlephobia. It specifies the exact resources and data points (license, advisories, bundle size, etc.), distinguishing it from simpler 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 triggers. It also mentions the ecosystem limitation and directs non-NPM users to 'deps.dev:version directly', offering an alternative.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds value by explaining the tool returns metadata (name, summary, record_count, owner/org, url) and that the URL is meant for downstream use, which goes beyond the annotation hints.

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

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

Two sentences, front-loaded with the core purpose, and includes useful parenthetical examples. Every word earns its place with no repetition of structured schema content.

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

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

With no output schema, the description compensates by stating the return fields. It also clarifies the domain (GIS open data) and the intended workflow with sibling tools, making it sufficiently complete for a simple search tool with good annotations.

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

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

Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds minimal parameter-specific meaning, mainly reinforcing that 'query' is a keyword search and that the returned URL feeds other tools, but it doesn't add syntax details 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 states a specific verb+resource+scope: 'Search Town of Grand Chute GIS open geospatial datasets... by keyword.' It clearly distinguishes from siblings by naming downstream tools (query_layer / layer_info) and specifying the return fields.

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: use this to find GIS datasets, then pass the returned URL to query_layer or layer_info. It implies this is the discovery step but doesn't explicitly state when not to use it, though the workflow is evident.

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. Beyond that, the description adds concrete behavioral details: the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), the 200K char cap with truncation flagging, and the fact that offsets are returned for verification. This goes well beyond the safety profile provided by annotations.

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

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

The description is front-loaded with the core purpose, then transitions naturally to usage guidance, return value details, and technical implementation. Every sentence serves a purpose: context, use case, behavior, pairing, and technical constraints. 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 takes responsibility for explaining return values, which it does: 'top-N passages with character offsets and similarity scores'. It also covers input constraints, usage context, and how to combine with a sibling tool. The unique aspects (truncation flag, offsets for verbatim verification) are disclosed, making this fully self-contained.

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?

Since the input schema covers 100% of parameters with descriptions, the baseline is 3. The description adds value by giving examples of what 'text' could be (SEC 10-K body, article, tool result) and clarifying the behavior of the text parameter (truncation cap). The query examples in the schema are already strong, but the description complements them with real-world usage 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 'Semantic search INSIDE a fetched record', which clearly states the verb (search), resource (record), and scope (inside a fetched record). It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and emphasizing its niche of searching within already-fetched text rather than grounding over whole documents.

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 when the record is too big to cram into the prompt' and positions the tool as a context-saving measure. It also names an alternative (ask_pipeworx_grounded) and explains how they pair, providing clear when-to-use and comparative guidance.

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

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

The description goes well beyond annotations by disclosing auth requirements, SMS verification and daily caps, webhook HMAC signing details, one-time secret display, and auto-disable after failures. No contradictions with annotations; idempotency is not explained but not contradicted.

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 purpose-first, packing a lot of necessary information into one paragraph. It earns its length given the tool's complexity, though bulleted type/channel sections would improve scannability.

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

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

Given the lack of an output schema, the description correctly mentions the returned subscription id. It thoroughly explains delivery behavior and prerequisites, but only details 3 of 5 subscription types in prose—patent_grant and clinical_trial are left entirely to the schema. Error cases and unsubscription flow are not covered, but sibling tools handle that.

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

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

The schema already provides rich descriptions for all parameters. The description adds valuable semantic examples (e.g., 'items:["5.02"] = officer change', 'topic:"fed"') and clarifies prerequisites, though much of the delivery parameter detail overlaps with the existing 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the verb (create), resource (subscription), and intent (monitoring), and distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

It provides solid context: requires a Pipeworx OAuth account, lists supported subscription types, and explains delivery channels. It mentions recent_alerts as an alternative for pulling the feed, but does not explicitly outline when one should avoid subscribe in favor of other query 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 provide readOnlyHint/idempotentHint, and the description adds valuable context: results are category-bucketed, drawn from a 'live catalog of thousands of tools,' and include tool+argument mappings. It also discloses that omitting topic returns the 'full spread.' These details enrich the agent's understanding of what the tool returns without contradicting annotations.

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

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

The description is a single dense sentence that front-loads example phrasings and then delivers purpose, behavior, parameter guidance, and usage context. While it lists many synonym-like phrasings at the start, each segment adds value, so it remains appropriately sized for an onboarding tool with zero 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?

With one optional parameter, no output schema, and strong annotations, the description fully covers the tool's inputs, outputs, and usage situations. It even mentions the live catalog and meta-tool learning, so an agent has enough context to invoke it correctly without any external information.

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

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

The schema already fully documents the single optional `topic` parameter (100% coverage), and the description adds concrete usage examples ('finance', 'pharma', 'betting') and clarifies the default behavior ('Omit for a cross-category spread'). This goes beyond the schema's basic type/enum list and gives the agent practical guidance.

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

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

The description states a specific purpose: 'the onboarding entry point' that 'returns category-bucketed example questions' with 'the exact tool + argument shape that answers it.' It uses a specific verb ('returns') and identifies the resource (Pipeworx tool catalog) and even includes example user phrasings, making the tool's purpose unmistakable and distinct from generic search or ask 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 clear when-to-use 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 parameter behavior. However, it does not explicitly name alternative tools (like discover_tools) to distinguish when not to use them, so it misses the highest bar.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral details: ownership enforcement and deactivation rather than deletion, with historical events remaining available via recent_alerts. This aligns with and supplements the annotation hints.

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

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

The description is two concise sentences, front-loaded with the primary action. Every clause adds value: cancel action, ownership, and deactivation semantics. There is no redundant or unrelated content.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, side effect (deactivation vs deletion), and the consequence for historical data. This is complete enough for an agent to use 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 already describes 'id' as a UUID returned by subscribe, so the parameter semantics are fully covered by schema_description_coverage=100%. The description does not need to add more, and 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 starts with 'Cancel a subscription by id', which is a specific verb and resource. It clearly distinguishes this from sibling tools like 'subscribe' and 'list_subscriptions' by the action and the added context of ownership enforcement.

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

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

The description provides clear usage context: it cancels a subscription by id and enforces ownership. It does not explicitly mention alternatives or when not to use it, but the behavior is straightforward and the ownership restriction serves as a practical guideline.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: it explains the SEC EDGAR + XBRL fast path with exact percent-delta math versus the grounded pipeline, discloses that it returns verbatim evidence, lists possible verdicts, and notes it replaces 4–6 sequential calls. This gives a clear mental model of internal behavior without contradicting annotations.

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

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

The description is a single dense paragraph but logically organized: trigger phrases, usage context, routing details, output specification, and performance benefit. Every sentence contributes meaning, and it remains readable despite its length. 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?

Even without an output schema, the description thoroughly covers return values (verdict types, actual value, citation, reasoning) and explains how different claim types are handled. It provides sufficient information for an agent to invoke the tool correctly and understand what to expect.

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 tool description does not add parameter-specific meaning beyond the schema; it references tolerance behavior indirectly ('exact percent-delta math') but does not explain claim or tolerance_pct further. The schema already provides examples, ranges, and the default cap, so the description adds no extra 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 purpose: natural-language claim verification against authoritative sources, reinforced by trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from siblings by describing a two-routed pipeline (SEC EDGAR for financial claims, grounded pipeline for others) and clearly differentiates from generic ask/research tools.

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

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

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and describes routing logic for different claim types. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, so it stops short of a 5.

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