chess

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

Discloses default model, cost implications (BYO Anthropic key), and return structure ({score, confidence, signals, raw_response} + combined view). Annotations already declare read-only/idempotent, so the description adds useful behavioral context beyond them.

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

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

Three tightly worded sentences: purpose/output, cost/config detail, use cases. Front-loaded with the core function; no filler.

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

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

For a read-only tool with good annotations and full schema coverage, the description includes the return shape and combined view, which is sufficient. It doesn't need to explain error handling given the straightforward probe operation.

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

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

Schema covers all parameters at 100%, but the description adds the specific default model name (Llama-3.3-70b), free tier, and clarifies the conditional relationship between `models` and `_apiKey` (Anthropic needs key, direct payment).

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'), names the resource (LLMs), and defines the outcome (visibility score 0-100 per model). It differentiates from sibling tools by focusing on AI/LLM knowledge scoring rather than generic question answering or 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?

Provides clear use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly list exclusions or alternative tools, but the context is sufficient for an agent to know when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable operational context: it routes to the right tool, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and does so in one fast call. This enriches the annotation baseline without contradicting it.

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 intentionally dense, front-loading the most critical directive ('PREFER OVER WEB SEARCH'), then explaining the mechanism, usage triggers, examples, and alternatives. Each sentence contributes meaningful guidance, though slight trimming would be possible 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?

For a complex routing tool with no output schema, the description covers the purpose, underlying architecture (5,529 tools, 1455 sources), the output format (structured answer with citation URIs), usage triggers, and explicit escalation paths to sibling tools. It also includes real-world examples, making it a complete and self-sufficient reference.

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%: the main 'question' property is described as 'Your question or request in natural language' and the aliases are each documented as aliases for question. The description itself adds little beyond the schema examples, 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 that ask_pipeworx answers factual questions by routing to thousands of verified sources and returning structured answers with citation URIs. It explicitly distinguishes itself from ask_pipeworx_grounded and deep_research, making its unique role clear.

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

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

The description gives explicit directives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives. It lists trigger phrases like 'what is', 'look up', 'find', and gives concrete examples, leaving no ambiguity about when to use this tool.

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

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

Beyond annotations, the description discloses that the tool may change behavior live when routing candidates are under test, and that currently no candidate is active so it matches ask_pipeworx exactly. It also states the response shape is identical to ask_pipeworx, providing transparency about behavior and output consistency. No contradiction with annotations.

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

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

The description is four sentences and effectively front-loads the key fact that this is a beta version of ask_pipeworx. Each sentence contributes meaningful context (beta nature, current state, usage instruction, non-fallback clarification), though the first sentence is somewhat dense with parenthetical details.

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

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

Given the tool's complexity as a routing wrapper, the description provides sufficient context: it names the stable counterpart, specifies the same arguments and response shape, explains the current inactive-candidate state, and clarifies it is a full working router. No output schema exists, but the description's reference to ask_pipeworx's response shape fills that gap adequately.

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

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

The input schema has 100% parameter coverage, with all six parameters documented as aliases for 'question.' The description adds no parameter-specific detail, but the schema fully describes the required natural-language question and its aliases. The description's mention of 'same arguments' as ask_pipeworx is redundant but not harmful.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router, and explains it is identical to the stable version except for experimental routing improvements. It distinguishes itself from the sibling ask_pipeworx by highlighting the beta/experimental nature, making the purpose unambiguous.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that when no candidate is active, it matches ask_pipeworx exactly, and that it is a full working router, not a fallback. This gives clear when-to-use and what-to-expect context relative to the stable alternative.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses key behavioral traits: it routes through other tools, makes an extra LLM call, extracts only from tool results, and returns specific refusal_reason values. It also details the exact response structure, adding significant context 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 densely informative yet carefully structured: purpose, mechanism, return/refusal formats, usage context, and cost comparison each occupy a distinct clause. There is no wasted wording, and the key differentiator ('grounded') is front-loaded, making it easy to grasp 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?

With no output schema, the description compensates by fully specifying both success and refusal response shapes, including enumerated refusal reasons. It also covers routing behavior, extra LLM call cost, and usage boundaries, making the tool's behavior and limitations clear for an agent without needing additional lookups.

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

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

Schema coverage is 100%, so the schema fully documents the single required parameter and its aliases. The description does not add parameter-specific details, but given the high coverage, the baseline of 3 is appropriate; the description's reference to 'routing' and 'question' is sufficient and does not need to repeat schema info.

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,' which clearly identifies the tool's specific purpose. It distinguishes from sibling ask_pipeworx by highlighting the grounded extraction behavior and explicit refusal mechanism, making the tool's unique role unmistakable.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), directly referencing the sibling tool and the cost trade-off. This provides clear, actionable guidance for tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=False, but the description goes far beyond that. It discloses the resolver contract (market_match_confidence, alternatives, suggestions), low-confidence short-circuiting, closed/dead market handling, wide-spread illiquidity warnings, and resolution-rule risk (cancellation rule parsing). This level of behavioral detail is exceptional and gives agents critical insight into failure modes and edge cases.

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

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

The description is long but extremely well-structured, using section headings (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) to break up dense information. It is front-loaded with the core purpose and clearly organizes optional details. Every sentence adds substantive value, though the volume is heavy and could be intimidating; a more concise summary might improve scannability without much loss.

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 return values, and it does so comprehensively. It covers result.market (order book stats), result.analysis (model probabilities, edge, Kelly fraction), result.evidence (keyed by source), resolver contracts, parent event handling, news field fallbacks, and safety statuses. It also addresses resolution-rule risks and blocking behavior. This is an exceptionally complete description 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 coverage is 100%, so the baseline is 3. The description adds concrete examples of how to format the 'market' parameter (slug, URL, question text) and explains the effect of include_raw on response size ('keeps responses under ~20KB' vs '50KB-500KB'). While the schema already provides these details, the description reinforces them with practical use context, nudging the score above baseline.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the input (slug, URL, or question text) and the output (evidence packet + market-vs-model comparison), and distinguishes from siblings by listing use cases like 'should I bet on X' and providing a classifier taxonomy.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples and blocking safety routes, giving clear context. However, it does not mention alternative tools or when NOT to use it, which would solidify the exclusionary guidance.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals specific data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting behavior by primary metric, and return format with paired data + citation URIs. This is rich, non-obvious 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 dense but every sentence earns its place: usage examples, preference rule, data-source details, sorting behavior, and output format. It is front-loaded with user-phrase examples that make recognition easy.

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 fully covers input constraints, entity types, data sources, behavioral nuances, and return format. The scale note ('Replaces 8–15 sequential lookups') gives context on efficiency, making it self-sufficient.

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

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

Schema covers 100% of parameter syntax, but the description adds semantic depth by explaining what each type pulls (company financials vs. drug adverse-event counts) and how values should be formatted (tickers/CIKs, drug names). This enriches the baseline 3.

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

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

Description opens with concrete example phrases and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call', making the tool's function unmistakable. It distinguishes itself from sibling tools like entity_profile by emphasizing parallel comparison vs. 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 gives an explicit directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and reinforces it by noting it 'Replaces 8–15 sequential lookups.' This clearly tells the agent when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses many behavioral traits: auth requirements, parallel decomposition, finding packet structure with gaps[] and contradictions[], the guarantee to 'never invented', semantic excerpting, resolvable citations, and expected latency. These details are far richer than what annotations alone provide, and they do not contradict any annotation.

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

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

Every sentence carries valuable information and there is no fluff, but the description is a dense wall of text that opens with account requirements rather than the core purpose. It could be better structured with sections or front-loaded with the main functionality, but given the tool's complexity, the length is justified and all content is relevant.

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

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

With no output schema, the description fully explains the return format: a findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[] for unanswered facets, and contradictions[] for standard/thorough depths. It also covers auth, usage, iteration behavior, and timing, making the tool usable without any additional documentation.

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

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

The schema already covers both parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds useful extra context such as concrete example questions, latency expectations per depth, and a note that depth:'thorough' requires a paid plan (already in schema). This modestly enhances understanding but is largely redundant with the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL, and returns a findings packet'. It explicitly contrasts itself with open-web search and sibling tool ask_pipeworx, leaving no ambiguity about what it 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 when-to-use and when-not-to-use guidance: it is 'Best for broad/multi-part questions over structured data', while 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives an account prerequisite and alternative fallback ('If you are not signed in, use ask_pipeworx instead'), meeting the highest standard for 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?

The description adds useful behavioral context beyond the annotations (read-only, idempotent) by explaining the return structure: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This tells the agent what to expect from the output, though it does not discuss edge cases or limits.

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

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

The description is three sentences, each earning its place: the first states the core purpose, the second details the return behavior, and the third gives usage timing. It is front-loaded with the action and avoids redundant filler, despite the moderately long list of domains which is informative.

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

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

Since there is no output schema, the description compensates by clearly explaining what is returned (top-N tools with schemas and examples) and when to use it. The parameter structure is simple and fully covered by the schema, so no further elaboration is needed. The description 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 the parameters are fully documented in the schema. The description's reference to 'top-N' aligns with the limit parameter's existing description, adding no extra parameter-level information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb and resource. It further distinguishes from sibling tools by positioning itself as a discovery tool for a broad set of domains (SEC filings, FDA drugs, etc.) and explicitly says to call it FIRST to see the option set, not just one answer.

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 use cases ('Use when you need to browse, search, look up, or discover what tools exist for...') and when to invoke it ('Call this FIRST when you have many tools available'). It does not name a specific alternative tool for narrow lookups, but the phrase 'not just one answer' implies a distinction.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavior: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; soft-fails patents due to API sunset; uses GDELT→GNews fallback; and returns specific fields with URI links and sorted output. No contradiction with annotations.

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

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

The description is long but dense, with trigger examples front-loaded and each technical detail earning its place. Slightly run-on with semicolon-separated lists, but no wasted words or redundant restatements.

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 enumerating key return sections: cik/company_name, recent_filings, fundamentals, patents, news, and LEI, with caveats and fallbacks. It doesn't specify exact JSON structure, but for a multi-source profile tool this is sufficient guidance.

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

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

Schema covers both parameters at 100%, so baseline is 3. The description adds value with concrete examples ('AAPL', '0000320193'), clarifies zero-padded CIK format, and reinforces that names are not supported, which goes beyond the schema's wording.

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

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

Description opens with concrete user intents and states 'full cross-source profile of a US public company in ONE parallel call,' clearly identifying the action and resource. It explicitly contrasts itself with chaining single-pack lookups and mentions resolve_entity for name-only inputs, helping distinguish it from sibling tools.

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

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

The description gives 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 states the exclusion for names and directs users to resolve_entity first, providing clear alternatives and prerequisites.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the context of clearing sensitive data but doesn't disclose additional behavior such as irreversibility or behavior for non-existent keys, though idempotency is already annotation.

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

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

The description is two sentences, front-loaded with the action, followed by use cases and a pairing tip. Every word contributes; no fluff.

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

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

For a simple, single-parameter destructive tool with comprehensive annotations, the description covers the action, when to use it, and how it relates to sibling tools. No output schema exists, so the lack of return-value documentation is acceptable.

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

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

The single parameter 'key' is fully described in the schema as 'Memory key to delete' (100% coverage). The description echoes 'by key' without adding format or lookup details, so it adds minimal information 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 exactly what the tool does ('Delete a previously stored memory by key') with a specific verb and resource, and it clearly differentiates from the related siblings 'remember' and 'recall' by positioning deletion as the inverse operation.

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 conditions ('context is stale, the task is done, or you want to clear sensitive data') and instructs pairing with 'remember' and 'recall', which implies the alternatives for storage and retrieval. It doesn't explicitly state when not to use it, but the conditions cover the main scenarios.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, and the description adds behavioral detail by explaining it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations without contradicting them, though it omits potential edge cases like rate limits or failure behavior, so a 4 is appropriate.

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

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

The description is structured with a clear opening sentence stating the core function, followed by a brief explanation of process and output, and a concise list of use cases. Every sentence contributes value, though the use-case list could be seen as slightly redundant with the opening. It is appropriately sized and front-loaded.

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

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

For a simple tool with two parameters and no output schema, the description covers the key context: it explains the input (URL), the process (fetch/extract), the output format (standard llms.txt markdown), and the deployment location ('drop at site-root/llms.txt'). It does not discuss error handling or rate limits, but given the tool's simplicity and annotation coverage, this 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 baseline is 3. The description adds minimal value beyond the schema: it mentions 'any URL' for the url parameter but does not elaborate on max_links beyond what the schema already provides. Since the schema fully documents both parameters, the description does not need to compensate.

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

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

The description clearly states the verb ('Generate') and resource ('a production-ready llms.txt file for any URL'), and explains the purpose of enabling AI crawlers to index a site. It also lists use cases that implicitly differentiate it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, but does not explicitly name alternatives, so it misses the top score.

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

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

The description provides explicit use cases ('Useful for: 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'), giving clear context for when to use the tool. However, it lacks any 'when not to use' guidance or explicit comparison to alternative tools, so it falls short of a 5.

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

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

Annotations already indicate a safe read-only, non-destructive, idempotent operation. The description adds context about the return payload (game URLs, time controls, results, ratings) and the date scoping, but does not disclose additional behavioral traits such as pagination, rate limits, or error handling. With annotations covering the safety profile, this is adequate but not rich.

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

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

Two sentences, front-loaded with the core action and resource, then returns info. Every word earns its place with no fluff or redundant 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 simple read-only tool with full parameter descriptions, an output schema, and comprehensive annotations, the description is complete. It states what the tool does, the date format, and the return content, leaving no major gaps.

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

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

The input schema provides full coverage (100%) with descriptions for all three parameters (year, month, username). The description adds the combined 'YYYY/MM' format and an example, but this is somewhat redundant with the schema and even slightly inconsistent (separate year/month vs. combined format). It does not materially improve understanding beyond the schema, 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 uses a specific verb ('Retrieve') and clearly identifies the resource (a player's completed games for a specific month), along with what it returns (game URLs, time controls, results, ratings). This distinguishes it from sibling tools like get_player and get_stats.

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 specifies the use case: retrieving a player's completed games for a specific month, with a required date format. It does not explicitly name alternatives or exclusions, but the context is unambiguous for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that the tool returns rankings with ratings and win percentages, but since an output schema exists, this adds limited extra value. No contradictions found.

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

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

Efficient single sentence that covers purpose and return content without redundancy.

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

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

For a zero-parameter tool with an output schema and solid annotations, the description is complete. It covers what data is returned and the organization by format.

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 tool has no parameters, so the baseline is 4. The description adds meaning by listing the valid formats (daily, rapid, blitz, bullet), which is not present in the empty schema, making it highly informative.

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: checking top-ranked Chess.com players, and lists specific formats (daily, rapid, blitz, bullet). This distinguishes it from related tools like get_games or get_player.

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

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

The description implies usage for leaderboard queries, but does not explicitly mention when not to use it or name alternatives. However, the context is clear from the tool name and sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing a safe read operation. The description adds the specific return fields (title, country, followers, join date, last online time), giving useful context beyond annotations without contradicting them.

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

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

The description is a single, front-loaded sentence stating the purpose, including an example, and listing the key return fields. Every word contributes value, with 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?

This is a simple tool with one well-documented parameter and an output schema (not shown but exists). The description sufficiently covers the purpose and expected return data, leaving no significant gaps for an agent to use it correctly.

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

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

The schema fully describes the single 'username' parameter, including case-insensitivity and examples, providing 100% coverage. The description adds minimal extra meaning, only repeating the example, so the schema carries the burden and the description adds little.

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 fetches a Chess.com player's profile by username, with a specific example ('hikaru'). It is distinct from sibling tools like get_games and get_stats by focusing on the player profile resource.

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

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

The description implies usage for retrieving profile data but does not explicitly mention when to use this tool over alternatives or provide exclusions. No guidance on when not to use it is given, so usage remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds that it returns current/best ratings and win/loss/draw counts, but doesn't discuss rate limits, data freshness, or error behavior. With annotations covering safety, the added context is useful but not rich.

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

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

Two sentences, front-loaded with the main purpose, and includes practical usage trigger examples. No redundant filler; every sentence earns its place.

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

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

For a one-parameter read-only tool with full annotations and an output schema, the description provides the function, scope, and example usage. It doesn't mention edge cases or limitations, but those aren't critical given the tool's simplicity and rich structured metadata.

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

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

The single 'username' parameter has full schema coverage ('Chess.com username'). The description doesn't add further meaning about parameter format or constraints, 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?

Description states 'Get a CHESS.COM player's ratings and game records across daily, rapid, blitz, and bullet formats' – a specific verb, resource, and scope. It also includes concrete example queries, making the tool's purpose unmistakable and distinguishing it from generic get_games/get_player 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 'PREFER for' with natural language examples, guiding the agent on when to select this tool. It doesn't mention what it should NOT be used for or name alternatives, which keeps it from a 5, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only profile. The description adds value by specifying the exact return fields and that only active subscriptions are returned by default, which is behavior beyond the annotations.

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

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

The description is two sentences long, with the first sentence establishing purpose and return fields, and the second providing usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, usage context, return fields, and default behavior. The annotations address safety, and the schema documents the parameter, making the tool fully understandable to an agent.

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

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

The schema description fully covers the sole parameter include_inactive, so the description does not need to repeat its semantics. The description adds negligible extra meaning beyond what the schema already provides, meeting the baseline for high schema coverage.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, 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 clear context for when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly name alternative tools, but the reference to adding and canceling implies subscribe/unsubscribe, giving practical 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 provide no safety hints, so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), the claim_token workflow for follow-up, and the fact that the team reads digests daily—all valuable behavioral context beyond annotations.

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

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

Although lengthy, every sentence earns its place—from purpose to exclusions to workflow details. The description is front-loaded with the core purpose and flows logically through triggers, scope, formatting, claim_token, and constraints. No fluff.

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

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

For a 4-parameter tool with no output schema, the description covers all critical aspects: what the tool does, when to use it, how to use parameters effectively, the claim_token follow-up mechanism, and operational constraints. The absence of an output schema is compensated by explaining what filing returns (claim_token).

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

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

Schema coverage is 100%, but the description adds meaning: it explains the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and gives message guidance ('don't paste the end-user's prompt'). It also contextualizes the type enum by mapping it to concrete scenarios.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly defines the feedback types (bug, feature, data_gap, praise) and distinguishes the tool from sibling tools by scoping it to Pipeworx connection tools only, with a unique claim_token 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?

Provides explicit when-to-use triggers: '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 includes a clear when-not: tools from other MCP servers should be filed there instead, with guidance on identifying Pipeworx 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?

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description reveals valuable behavioral traits: it is a 'self-aggregating signal' derived from the CF analytics-engine, guarantees 'no PII', returns only '(pack, tool, count)', and is cached for 5min-1h depending on window. This additional context about data provenance, privacy, and freshness goes far beyond the annotations and clearly informs the agent.

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

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

The description is efficiently structured: the lead sentence states the core output, the second sentence lists concrete use cases, and the third adds technical context about data source, PII, and caching. It is slightly longer than strictly necessary, but every sentence contributes distinct value and it is front-loaded with the primary purpose. This earns a 4 rather than a 5.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers the essential aspects: what is returned, how to choose the window, use cases, and data freshness. It does not specify the exact output format or edge cases, but the mention of '(pack, tool, count)' and the absence of an output schema make it sufficiently complete for a straightforward read-only trending 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 provides 100% coverage for the only parameter (window) with an enum and a detailed description differentiating short vs. long window semantics. The tool description merely repeats the allowed values without adding new meaning, so the baseline of 3 is appropriate. It does not enrich the parameter's semantics beyond the schema.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume' over a recent window, making the specific verb and resource explicit. It distinguishes itself from siblings like discover_tools by focusing on what other AI agents are calling on Pipeworx, a unique aggregative signal. The purpose is 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 provides explicit when-to-use guidance via three enumerated use cases, such as confirming a popular tool is canonical or aligning with agent needs. It also gives window-selection guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not mention when not to use the tool or explicitly name alternative sibling tools, so it stops short of a full 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses nuanced behaviors: it walks child markets, computes partition sums, filters placeholder slugs, enforces Jaccard similarity, and runs a live CLOB fill-check with a clear 'do not trade' condition. This is rich, non-obvious context with no contradiction to annotations.

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

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

The description is long but well-structured with labeled sections and front-loaded purpose. Every sentence covers a distinct rule, mode, or output field, so the length is justified for the tool's multi-mode complexity. 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 enumerates the return structure (`opportunities[]`, `partition_check`, `realizable_edge_pp`, `thin_legs[]`) and documents edge cases and fallbacks. It also references a related tool for sizing, making the tool effectively self-contained for an agent.

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

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

While the schema already covers both parameters, the description adds significant meaning: the no-arg default behavior, event slug/URL examples, topic seed question examples, and the specific checks each mode performs. It turns simple string parameters into actionable mode selectors.

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 opening sentence states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, naming the resource and method explicitly. It further distinguishes modes (no-arg trending scan, event-specific, topic cross-event), making it clear how this differs from sibling tools.

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

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

The description gives explicit when-to-use instructions: no args for a broad trending scan, `event` for a specific market, and `topic` for cross-event scanning. It also names an alternative tool for custom sizing (`polymarket_fill_risk`) and warns when not to trade a signal, satisfying the when/when-not requirement.

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 as read-only, open-world, and idempotent; the description adds substantial behavioral context, including the three response segments, the caching at the KV level with 1h TTL, the exclusion of Fed bets from ranking due to unreliable signals, and the diagnostic counters (filter_skips, funnel counters) that explain why segments may be empty. This goes far beyond the safety hints and no contradictions exist.

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

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

The description is long but densely organized with numbered model families, response segment labels, and knob subsections, ensuring all key information is front-loaded after the core purpose. Each sentence adds functional value—explaining edge computation, caching, or diagnostics—rather than padding, though the length may be slightly demanding for an agent scanning 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?

With no output schema present, the description fully compensates by detailing the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), which is critical for callers to interpret results. It also covers the three model families' logic, the tradeable-edge knobs, and the 1h KV cache, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% parameter descriptions, and the description adds contextual meaning by grouping parameters as 'Tradeable-Edge Knobs' (min_liquidity, max_spread_pp) and clarifying subtleties like why min_kelly does not filter partition_overround (parent-level kelly is 0 by design) and the per-leg slippage rationale. This enhances the schema's already-strong 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 opening sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with an explicit use case ('what should I bet on today'). This specific verb-resource pairing distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker, which focus on arbitrage or tracking rather than opportunity 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 explicitly frames the tool's intended usage: agents discovering opportunities without paging hundreds of markets, and provides context for knobs (e.g., 'Tradeable-Edge Knobs') that adjust threshold behavior. However, it does not explicitly name alternative tools or state when to avoid this tool in favor of siblings like polymarket_arbitrage or polymarket_fill_risk, so it stops short of a full when/when-not guide.

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

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

The description goes well beyond the annotations (readOnly, idempotent, openWorld) by explaining data gaps ('snapshots are written when polymarket_edges runs on a cache-miss'), limits (60-day TTL, daily closes not intraday), and response structure (tracked, expired, snapshot_dates). This provides deep behavioral context without contradicting the annotations.

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

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

The description is long but efficiently organized: purpose first, then explicit 'Args' and 'RESPONSE' sections, then 'LIMITS'. Each sentence carries useful information, with clear labels (tracked[], expired[], snapshot_dates[]) that make the structure scannable despite 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?

Given the tool's complexity (time-series analysis, no output schema, nuanced behavior), the description is exceptionally complete. It fully specifies return fields, trend categories, decay calculation, edge direction semantics, and limitations, leaving no critical gaps for an agent to proceed.

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

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

Schema coverage is 100%, and the description restates defaults ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding new semantic meaning beyond the schema. It does not clarify parameter behavior beyond what the schema already documents, 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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges by focusing on temporal persistence rather than current edge values.

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

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

The description implies when to use this tool: when you care about an edge's age and decay, contrasting fresh vs. 3-week-old edges. It references polymarket_edges as the source, suggesting the alternative for current edges, but does not explicitly name alternatives or exclusion criteria.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, which the description aligns with (it's a risk-check tool). The description goes well beyond annotations by detailing what the tool returns (top_of_book, vwap_fill_price, slippage_pp, verdict, capture_ratio, thin_legs, forced_directional_risk) and behavioral nuances like partial fills leading to unhedged positions. No contradictions.

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

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

The description is dense but well-structured: it leads with the core purpose and requirements, then separates SINGLE-MARKET and BASKET modes, and ends with explicit usage guidance. Every sentence adds value, though the length is substantial. A slight reduction or bullet-point formatting could improve scannability, but no information is wasted.

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

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

This is a high-complexity tool with two modes, no output schema, and only four parameters. The description enumerates all key return fields for both modes, names the risk of partial fills, identifies `thin_legs` and `forced_directional_risk`, and gives concrete threshold guidance ($500). It fully compensates for the lack of an output schema and leaves no major gaps.

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

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

While schema coverage is 100%, the description adds substantial semantic depth beyond the property descriptions. For instance, it clarifies `size_usd` as 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional — shares per leg' in basket mode. It also explains the default behavior for `side` in basket mode (auto from partition sum). This significantly enriches parameter understanding.

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

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

The description opens with a specific noun phrase, 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and immediately clarifies the tool's core function: verifying whether theoretical edges are actually capturable given market depth. It clearly distinguishes single-market and basket modes, and its relationship to sibling tools like polymarket_arbitrage and polymarket_edges is explicit.

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

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

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when single-market vs basket modes are appropriate, and warns of the danger of partial basket fills converting into unhedged positions. This fully addresses when to use the tool versus alternatives.

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

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

Despite having strong annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds substantial behavioral detail: compatibility_warning conditions, temporal_alignment meaning, skipped_cross_type/subtype counters, and the explicit caveat that pre-mapped ≠ tradeable. This goes far beyond the annotations without contradicting them.

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

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

The description is long but well-structured, using uppercase headings (TWO MODES, RESPONSE, SAFETY FIELDS) to organize dense information. Every sentence adds practical value, and the final caveat is crucial. Despite its length, it earns its place.

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

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

With no output schema, the description must explain return values, and it does: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. Given the tool's complexity (3 parameters, two modes, multiple edge cases), the description is complete and self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes (topic vs explicit) and how the parameters interact (overrides), which is not fully clear from the schema alone. It also lists the exact topic shortcuts, reinforcing the schema.

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

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

The description clearly states what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs and resources, and the explanation of venue pricing differences distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides clear context on when to use the tool: for cross-venue spreads, with two modes (topic shortcuts vs explicit pairings). It also warns that most pre-mapped topics may not be tradeable, giving users a when-not expectation. However, it does not explicitly name alternative tools or contrast with siblings, keeping it a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds useful behavioral context about scoping: "Scoped to your identifier (anonymous IP, BYO key hash, or account ID)." It also clarifies the dual behavior of listing all keys when the argument is omitted.

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

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

The description is three concise sentences, each earning its place. The first sentence front-loads the action, the second gives usage context, and the third covers scoping and relationships. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description is complete. It explains the tool's behavior, scope, and relation to remember/forget, leaving no significant gaps for an agent to misuse it.

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

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

Schema coverage is 100% (the key parameter is described in the schema). The description adds value by providing examples of what keys represent ("user's target ticker, an address, prior research notes") and by explicitly explaining the omit-to-list behavior, which enriches the schema's minimal description.

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

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

The description clearly states the tool's function: "Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)." This specifies the verb (retrieve/list) and resource (saved memory), and distinguishes it from sibling tools like remember and forget.

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

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

The description explains when to use the tool: "Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch." It also references sibling tools ("Pair with remember to save, forget to delete") but lacks an explicit when-not-to-use condition.

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

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

The description states 'Set mark_read:true to flag returned events read,' which modifies state, but the annotations declare readOnlyHint: true. This is a direct contradiction, as the tool can change the persisted feed's read status. Per rubric, this mandates a score of 1.

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

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

The description is front-loaded with purpose and covers key behavioral points in a few sentences. It includes a useful alternative endpoint, but the length is slightly beyond minimal and could be tightened. Still, every sentence adds value.

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

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

Despite lacking an output schema, the description explains the return fields (source, citation_uri, raw payload) and covers filtering and read-state behavior. It does not elaborate on pagination or ordering beyond 'most recent,' but overall it is sufficiently complete for a moderately 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it gives an example type ('sec_8k'), clarifies the semantics of mark_read (affects future calls), and explains unread_only behavior. This lifts the score above baseline.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and describes the returned data (source, citation_uri, raw event payload). This distinguishes it from siblings like list_subscriptions and ask_pipeworx by focusing specifically on retrieving fired alerts.

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

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

The description provides clear context on when to use the tool (to fetch recent alerts), and even offers an alternative HTTP endpoint for scripts/dashboards. It also hints at polling use cases, but does not explicitly state exclusions or when to prefer alternatives, so not a full 5.

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

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

Annotations already declare readonly/idempotent/non-destructive hints, but the description adds rich behavioral detail: fan-out to SEC/GDELT/GNews/USPTO, fallback logic (GDELT preferred, GNews on rate limiting), API sunset soft-fail, and the 'ONE parallel call' execution model. This genuinely exceeds what annotations convey.

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

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

Front-loaded with example queries that immediately convey purpose. Dense but every sentence earns its place: source breakdown, fallback behavior, date formats, return shape, and cross-reference. No filler.

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

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

Despite no output schema, the description explains return format (changes[] grouped by source, total_changes count, citation URIs). It covers sources, fallback rationale, date syntax, and entity type constraints. Complex multi-source tool with no obvious missing context.

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

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

Schema covers all 3 parameters at 100%, so baseline is 3. The description adds value by explaining 'since' accepts ISO or relative shorthand and recommending '30d' for typical monitoring. It doesn't duplicate the schema's value/type specifics but provides practical 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 example queries ('What's new with X' / 'latest on Y'), then precisely states 'change feed for a company in the last N days'. It explicitly distinguishes from the sibling tool entity_profile, making the 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?

Provides explicit guidance on when to use this tool (change feed) and explicitly names the alternative (entity_profile for static profile regardless of window). Also gives usage tips like 'Use 30d for typical monitoring'.

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 meaningful behavioral context beyond annotations: it explains scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. It also notes cross-session storage. These details are not present in annotations and help the agent understand the tool's side effects.

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

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

The description is concise and well-structured: the first sentence states the core purpose, the second gives usage guidance, the third explains storage scoping, and the final sentence points to related tools. Every sentence adds value with no redundancy.

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

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

For a simple key-value storage tool with no output schema and full schema coverage, the description is complete. It covers what, when, how, retention, and relationships to alternatives, making it fully actionable for an agent.

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

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

Input schema already has 100% coverage with descriptions for both key and value. The description adds extra context by explaining the key-value pair semantics and scoping by identifier, which enriches the meaning of the parameters beyond the schema alone.

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 with a specific verb ('Save data') and resource ('data the agent will need to reuse later'), and distinguishes it from siblings by explicitly pairing with recall and forget. Examples of use cases (ticker, address, preference, research subject) further clarify the purpose.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward...') and mentions alternatives ('Pair with recall to retrieve later, forget to delete'). This clearly differentiates when to use remember versus sibling tools.

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

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

The description adds rich behavioral context beyond the readOnly/openWorld/idempotent annotations: it explains that identifiers are source-labelled, unresolved identifiers are explicitly listed under 'unresolved', enrichment degrades gracefully, and internal cascading across endpoints occurs. 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 a single dense paragraph but highly front-loaded with examples and guidance. It could be broken into bullets for easier scanning, but every sentence adds value and there is no fluff. Slightly long for a tool description, yet justified by the tool's complexity.

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

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

Given the two entity types, the absence of an output schema, and the annotations, the description covers all critical aspects: purpose, accepted inputs, enrichment sources, degradation behavior, and how unresolved IDs are handled. An agent can confidently invoke this tool with the correct 'type' and 'value' format.

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

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

Although schema coverage is 100%, the description adds significant semantic detail: it maps 'type' to entity categories (company/drug), details what 'value' accepts for each type (ticker, CIK, name; brand/generic), and explains the output context for resolved vs unresolved identifiers, enriching the bare schema definitions.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers. It provides multiple concrete examples (ticker, CIK, LEI, RxCUI) and distinguishes its purpose from siblings by emphasizing it produces IDs other tools require as input.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also notes that using resolve_entity replaces 2-3 manual lookups, implying it is a bundling/preferred approach. The supported types and accepted input formats clarify when to use it.

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

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

Discloses it 'Probes each entity (your brand + N competitors) with ai_visibility_check' and 'ranks by score', plus the return format 'ranked list with score, confidence, signal density per entity' — adding behavioral depth beyond the readOnly/idempotent annotations.

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

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

Three sentences, front-loaded with the primary action, no fluff. Each sentence adds either function, internal process, or usage context.

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 covers both behavior and return format. It also explains the relationship to ai_visibility_check and gives a practical example, making it 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?

Schema already covers all 4 parameters at 100% with detailed descriptions. The tool description adds no extra parameter semantics beyond a passing 'your brand + N competitors' that's already in the entities field description.

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

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

Description opens with 'Compare AI visibility across multiple entities side-by-side' — a specific verb+resource+scope. It distinguishes from sibling ai_visibility_check by explicitly stating it probes each entity and ranks them.

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

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

Provides a concrete use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' and explains the multi-entity scope. It doesn't explicitly state when not to use, but the context is clear.

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

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

The description adds significant behavioral context beyond the annotations: it is a composite call that fans out to two services, it degrades gracefully on partial failures, and bundlephobia's first measurement can take 5-30s, with sources_failed listing timeouts. It also details the exact return block (is_latest, license, etc.), which the annotations do not provide. No contradictions with the readOnly/idempotent 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 dense but every sentence earns its place: it covers purpose, usage triggers, return fields, ecosystem scope, and failure behavior. It is well-structured with clear separations, and there is no redundant or filler content. The use of parentheses and lists makes the information scannable.

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

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

Despite lacking an output schema, the description lists the exact return fields (summary block, per-advisory detail, links, alternative versions), explains the NPM-only constraint, and describes partial failure behavior. This is complete for a tool of this complexity, and the annotations cover safety and idempotency, so nothing essential 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 coverage is 100%, so parameters are fully documented in the input schema itself. The description does not add significant new meaning beyond what the schema already provides (e.g., 'package' and 'version' are self-explanatory). The description's mention of defaults and scoped packages is already present in the schema, so no extra value.

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

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

The description clearly states the tool is a composite check for 'should I add this npm package to my project', specifying it fans out across deps.dev and bundlephobia. It names specific resources and functions (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support). This distinguishes it from sibling tools that focus on other areas like research or entity profiles.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing concrete triggers for use. It also gives exclusions and alternatives by stating 'NPM ecosystem only in v1' and that other ecosystems 'fall under deps.dev:version directly'. This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavior: a 200K character cap with truncation and flagging, embedding method, window size, and that returned passages include offsets for verification. This adds real context for safe invocation, especially the truncation behavior.

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 rich; every sentence adds information. It front-loads the core function, then usage, then technical details. No fluff 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?

For a tool with no output schema, the description fully informs about return format (passages, offsets, similarity scores), constraints (size cap), and pairing. Combined with strong annotations, the agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining text cap, giving example queries, and implying 'top-N' limit behavior. It doesn't restate schema descriptions but provides usage context, so a 4 is appropriate.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which uses a specific verb and resource, clearly distinguishing it from sibling tools. It further differentiates by stating it returns passages with offsets, unlike general ask_pipeworx tools. The purpose is unmistakable and scoped.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt,' providing a clear when-to-use condition. It also contrasts with feeding the whole document, and mentions pairing with ask_pipeworx_grounded, effectively outlining when to choose this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses significant behavioral traits: auth persistence requirements, always-on feed behavior, SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 failures. These details go well beyond what annotations provide, giving agents a clear picture of side effects and constraints. No contradiction with annotations found.

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

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

The description is long but well-structured: it front-loads the purpose and return value, then organizes supported types and delivery channels into clear sections. Each sentence adds necessary operational detail. While it could be trimmed slightly (e.g., some redundancy with the schema), the density of useful information 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?

Given the high complexity (nested objects, multiple types, optional delivery channels) and the absence of an output schema, the description is remarkably complete. It covers return values, auth requirements, type-specific parameters, delivery options, verification steps, rate limits, and failure behavior. This effectively compensates for the missing output schema and provides agents with enough context 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 coverage is 100%, so the baseline is 3 per the rubric. The description adds extra semantic value by mapping item codes to meanings (e.g., items:['5.02'] = officer change) and providing concrete examples for each subscription type. It also clarifies delivery constraints (phone verification, caps) that aren't fully detailed in the schema, so it adds genuine meaning beyond the structured fields.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the primary action and distinguishes this from sibling tools like list_subscriptions and unsubscribe by focusing on creation. Returning the new subscription id is also mentioned, reinforcing the tool's purpose.

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

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

The description provides clear context for when to use the tool (proactive monitoring), prerequisite auth requirements (Pipeworx OAuth account), and detailed examples for multiple subscription types. However, it does not explicitly contrast with alternatives like recent_alerts or list_subscriptions, leaving some implicit guidance around when to choose this vs. other monitoring or retrieval tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds valuable context by describing the returned structure ('category-bucketed example questions... with the exact tool + argument shape') and parameter behavior ('Call with no arguments for the full spread, or pass topic to focus'). No contradiction with annotations.

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

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

The description is longer than ideal, with repeated question paraphrases at the start, but it is appropriately sized for a complex tool with many categories and usage modes. It is front-loaded with the core purpose and quickly moves to return format and usage, with no wasted sentences.

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

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

The description fully explains the tool's purpose, return format, parameter semantics, and usage context. Since there is no output schema, it covers the return values thoroughly by listing categories and the tool+argument shape. It also explains the live catalog aspect and how to focus with the topic parameter, making it complete for an onboarding 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% for the single 'topic' parameter, and the schema already lists the exact focus areas and the omit behavior. The description repeats these values ('finance', 'pharma', 'betting') without adding new meaning beyond a slight emphasis on focusing. Thus it adds minimal value over the schema.

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

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

The description clearly identifies the tool as an onboarding entry point that 'returns category-bucketed example questions' with exact tool and argument shapes. It uses specific verbs like 'suggest' and 'onboard' and distinguishes itself from siblings like ask_pipeworx by focusing on generating examples rather than answering queries directly.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides a strong when-to-use directive. However, it does not explicitly state when not to use it or name specific alternative tools for other scenarios, though it mentions learning how to call meta-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 only state readOnly=false, destructive=false, and idempotent=true. The description goes further, explaining that rows are deactivated rather than deleted, ownership is enforced, and historical events remain available. This provides valuable behavioral context 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?

Two sentences, front-loaded with the action. Each sentence adds critical information: the operation, the constraint (ownership), and the side effect (deactivation + historical availability). No filler.

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

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

For a single-parameter mutation tool with clear annotations and no output schema, this description covers the purpose, constraint, and side effects. It's complete for an agent to decide and invoke correctly.

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

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

The schema already describes the id parameter as the subscription UUID returned by subscribe, giving 100% coverage. The description adds only 'by id,' which doesn't enrich beyond the schema. Baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'subscription by id', immediately distinguishing it from sibling tools like subscribe and list_subscriptions. It also adds the deactivation detail, reinforcing 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?

It provides clear context: ownership is enforced and cancellation only applies to own subscriptions. It also signals that historical events remain accessible via recent_alerts, indirectly guiding when not to use this tool (if preserving history is needed, use recent_alerts). However, it doesn't explicitly name alternative tools for cancellation.

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

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

The description goes well beyond the annotations: it discloses the SEC EDGAR/XBRL fast path vs. grounded fallback, the verdict set, citation style, error semantics, and the fact that it replaces multiple sequential calls. Annotations declare read-only/idempotent, which the description confirms 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 moderately long but well-structured: user-intent patterns first, then routing logic, return contract, error semantics, and a performance note. Every clause earns its place, though it could be slightly tighter without losing the important caveats.

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

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

Without an output schema, the description fully specifies return values (verdict list, value, citation, reasoning), error semantics (could_not_verify vs unsupported), and routing details. It is self-sufficient for an agent to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning to tolerance_pct: it explains default behavior (implied by wording, capped at 5), explicit use for hallucination detection (1–2), and the range. This goes beyond the schema's dry description of 'max percent deviation'.

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?

Purpose is explicit and specific: natural-language claim verification against authoritative sources, with concrete example queries. It clearly distinguishes itself from generic Q&A siblings like ask_pipeworx by framing it as a fact-check/verify tool and noting it replaces a multi-step pipeline.

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

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

States exactly when to use: whenever the agent needs to check factual correctness. Gives routing guidance (company-financial vs. other claims) and explicitly explains the meaning of could_not_verify and unsupported, preventing misuse. No competing alternative is named, but the scope is unambiguous.

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