stackexchange

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

Annotations already declare readOnly=true and idempotent, so the description doesn't need to restate that. It adds valuable context by revealing the default model (Workers AI Llama-3.3-70b), cost implications of using Anthropic, and the precise return structure, making behavior transparent. 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?

Three sentences, front-loaded with the core purpose, followed by defaults/cost and return structure. Every sentence earns its place, no filler.

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

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

Given there is no output schema, the description compensates by specifying the per-model and combined view, plus default model and use cases. It covers all essential aspects: what it does, default behavior, extension, and return 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?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by specifying that `models` defaults to workers-ai and that `_apiKey` is passed straight through and incurs direct cost, adding practical usage meaning.

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

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

The first sentence clearly states the action and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This specific verb+resource distinguishes it from siblings like scan_competitor_ai_presence or compare_entities, making it unmistakable what this 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 concludes with 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving explicit contexts where this tool fits. It also explains when to include `_apiKey` for Anthropic, but does not explicitly name alternatives, so it doesn't earn a 5.

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

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

Beyond annotations (readOnly, openWorld, idempotent), it discloses routing behavior, auto argument-filling, citation URIs, tier compatibility, and speed expectations. 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?

Front-loaded and informative, but somewhat repetitive ('Use whenever', 'START HERE', 'Step up only when needed' overlap); still every sentence carries useful guidance.

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

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

For a single-required-param tool with no output schema, the description thoroughly covers purpose, triggers, data scope, alternatives, return format, and limitations, making it sufficient for agent selection and invocation.

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

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

Schema covers the question parameter and aliases at 100%, and description adds trigger examples and clarifies that the tool auto-fills sub-arguments, though it doesn't add new parameter syntax details.

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

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

The description clearly identifies the tool as a routing/answer engine for factual questions, with a specific verb ('Routes the question'), resource scope ('5,529 tools across 1455 verified sources'), and explicit differentiation from siblings (ask_pipeworx_grounded, deep_research).

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

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

It explicitly says to prefer over web search, gives trigger phrases ('what is', 'look up', 'find'), states 'START HERE' as default, and names alternatives to step up to when needed.

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, and idempotent hints, the description adds valuable context: it is a beta version, candidate improvements may go live at any time, no candidate is currently active so it matches ask_pipeworx exactly, and it is a full working router with no fallback. This transparently sets expectations about potentially changing 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 four sentences long and moderately detailed, but every sentence earns its place: definition, current status, usage directive, and a clarification that it is not a fallback. It is slightly verbose but well-structured and front-loaded with the key 'Beta version of ask_pipeworx' framing.

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 references 'same response shape' as ask_pipeworx, which is helpful if the sibling tool is known but not fully self-contained. It explains the current state and experimental nature but does not detail the routing mechanism or what changes when a candidate is active, leaving some gaps for a complex tool.

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

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

Schema description coverage is 100% with all six parameters (question plus five aliases) fully documented. The description adds no new parameter semantics beyond noting 'same arguments' as ask_pipeworx, so it relies on the schema, which is sufficient for the baseline score.

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 variant of ask_pipeworx, a universal router with the same 5,529 tools and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, so the purpose is unambiguous and well-differentiated from siblings.

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

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

The description explicitly states to use it exactly like ask_pipeworx when you want the newest routing, giving clear context for when to choose this tool. It also notes results are compared against the stable router, implying a testing role, but stops short of explicit exclusions (e.g., 'don't use for stable tasks').

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 that it extracts answers only from tool results, returns verbatim evidence, and gives specific refusal reasons. Adds cost and routing context beyond the annotations (readOnly, idempotent), with no contradictions.

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

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

Three dense sentences, each earning its place: first defines purpose, second details behavioral contract and returns, third gives usage guidance and cost tradeoff. Front-loaded and highly efficient.

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

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

Despite lacking an output schema, the description fully specifies both success and refusal result shapes, evidence inclusion, and cost/alternative guidance. It is self-sufficient for an agent to select and invoke correctly.

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

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

The schema already documents all parameters with 100% coverage, including aliases. The description mentions 'fills arguments' but does not add parameter-level semantics beyond what the schema provides, so baseline 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's verb, resource, and scope. It distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

Provides explicit when-to-use ('Use whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups'), directly naming the alternative and noting the extra LLM call cost.

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 is exceptionally rich with behavioral disclosures beyond the annotations: resolver contract (match_confidence, alternatives), safety short-circuiting (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity flags, and resolution-rule risk (refund_50_50, resolves_no_on_cancel). It also details fan-out behavior and news backfill fallbacks. This far exceeds the read-only/idempotent annotations and adds critical constraints for safe use.

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 all-caps section headers and concrete examples. Each section (RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) adds unique, necessary behavioral context. It is slightly verbose with the FAN-OUT EXAMPLES, but those examples directly aid the agent's understanding of fan-out behavior. Front-loaded with purpose, it earns its 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 no output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence), resolver disclaimers, parent_event extraction, news fallback fields, and blocking edge cases. It even includes a safety warning about cancellation rules and flat-50¢ void settlements. The tool is highly complex, and the description leaves no critical gap in what the agent needs to know before invoking.

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

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

Schema coverage is 100% with good parameter descriptions, giving a baseline of 3. The description adds extra value by explaining input variants ('slug, full URL, or question text'), resolution behavior, and the meaning of depth through concrete fan-out examples (BTC bet → coingecko + fred + gdelt+gnews). It also clarifies include_raw's size implications and recommended usage, going beyond the schema.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', which clearly states the verb (research), resource (Polymarket bet via Pipeworx data), and scope (one call). It distinguishes from siblings by emphasizing the one-call fan-out and market-vs-model comparison, differentiating it from generic ask_pipeworx or polymarket_edges 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 explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear context for when to invoke this tool. However, it does not explicitly state when not to use it or name alternative tools like ask_pipeworx for general questions, so it falls short of the full 5 criteria.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context by disclosing specific data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, sorting by primary metric, and the return of citation URIs—all 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 dense with useful information, front-loaded with the exact user phrasings it matches. No wasted words; each sentence contributes to understanding purpose, usage, or behavior. It's long but appropriately sized for a tool with two parameter types and rich behavioral details.

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

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

Even with no output schema, the description explains returns ('paired data + pipeworx:// citation URIs per entity') and sorting behavior, closing the gap. It also specifies limits (2–5) and source logic, making it sufficient for an agent to select and invoke correctly without external docs.

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 further elaborates parameter semantics by explaining what 'type' selects (company vs. drug) and the exact metrics pulled for each, plus examples for values. This adds meaningful depth beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, listing trigger phrases like 'compare X and Y' and 'X vs Y'. It also distinguishes itself from sequential single-entity lookups, which differentiates it from a sibling tool like entity_profile.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use directive. It also covers both entity types (company/drug) and implies the alternative of sequential lookups, though it doesn't name specific sibling tools beyond that 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 annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses account requirements, paid tier for thorough depth, decomposition into facets, parallel routing to 5,529 tools, findings packet structure with gaps[] and contradictions[], citation_uri resolvability, hop field semantics, semantic excerpting, and latency expectations. 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 densely informative; every sentence adds unique value (account prerequisite, alternatives, output structure, depth behaviors, latency). Front-loaded with the critical sign-in requirement. Slightly over-long for a quick scan, but appropriate given the tool's complexity and the absence of an output schema.

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 complex tool with no output schema, yet the description thoroughly covers the return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), gaps[], contradictions[], hop fields, semantic excerpting, and operational behaviors like latency and depth-dependent iteration. It leaves very little about tool behavior unstated.

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 provides detailed descriptions for both parameters (100% coverage), including depth enum semantics. The description adds value by explaining latency differences across depths, the account/payment implication of 'thorough', and what kind of question phrasing is appropriate for the broad question parameter. It complements rather than merely repeats the schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with specific distinction from open-web search and explicit contrast to ask_pipeworx. It names the verb (research), the resource (structured data sources), and the scope (broad/multi-part questions), fully distinguishing it from siblings.

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

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

Extensive when-to-use guidance: 'Best for broad/multi-part questions over structured data', explicit exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and account prerequisites ('If you are not signed in, use ask_pipeworx instead'). Also explains depth-level choices for different research needs.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, which are reinforced by the description's non-destructive nature. The description adds valuable behavioral context: it returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)', and that each result is 'ready to call directly, no second schema lookup needed'. This goes beyond the structured annotations and helps the agent predict the tool's output and 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 four sentences, front-loaded with the core purpose, followed by usage triggers, a list of covered domains, output format, and strategic guidance. Each sentence adds necessary information without fluff. It is slightly lengthy but every part contributes to understanding the tool's role and behavior.

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

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

For a simple discovery tool with one required parameter and no output schema, the description adequately covers return format ('top-N', names, descriptions, full schemas), usage context ('Call this FIRST'), and the type of query accepted. It also handles the potential need to reason about the large sibling toolset by grounding the description in concrete task examples and domain coverage. A minor gap is the lack of explicit error behavior or edge cases, but that is not critical for this tool.

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

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

The input schema has 100% coverage, as all parameters (query, q, task, limit, search, description) are described with meanings and aliases. The description adds no additional parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states 'Find tools by describing the data or task', which clearly specifies the verb (find) and resource (tools). It differentiates from siblings by positioning itself as a discovery meta-tool, noting it should be called FIRST when many tools are available, which distinguishes it from the specific domain tools listed as siblings.

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

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

It provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It also hints at an exclusion by saying 'not just one answer', implying a tool like discover_tools is for browsing the option set. Although it doesn't name specific alternatives, the context 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond those: it fans out across SEC, XBRL, USPTO, news, GLEIF; discloses the USPTO PatentsView API sunset May 2025 with soft-fail behavior; and notes the GDELT→GNews fallback. It also specifies the exact return fields. This goes well beyond the annotations.

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

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

The description is long but information-dense. It front-loads with user intents, then the core function, followed by return details and constraints. While a bit verbose, each clause earns its place; the structure helps an agent quickly identify purpose and limitations. Not as tight as two sentences, but not wasteful.

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

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

With no output schema, the description must explain return values—it does so thoroughly: CIK, company_name, recent_filings with URIs, fundamentals with specific metrics, patents, news, and LEI. It also covers edge cases (null results, API sunset, unsupported names). For a two-parameter tool, this is highly complete.

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

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

Input schema covers 100% of parameters with descriptions. The description adds extra meaning by giving concrete examples ('AAPL', '0000320193') and clarifying that value must be a ticker or zero-padded CIK, plus the caveat about names not supported. This enriches but does not significantly alter the schema semantics, 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 concrete user intents ('Tell me about X', 'research Acme') and explicitly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from siblings like resolve_entity (name resolution) and compare_entities (comparison) by focusing on a single entity and aggregating multiple sources.

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

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

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' and lists example queries. It also provides exclusions: 'names not supported (use resolve_entity first if you only have a name).' This is strong usage direction with a named alternative.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description's 'Delete' wording aligns without contradiction. No additional behavioral context (e.g., permanence, side effects) is provided beyond the annotations, but the risk profile is fully captured by the annotations.

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

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

The description is three short sentences: the action, the usage guidance, and the sibling pairing. It is front-loaded and contains 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 1-parameter delete tool with comprehensive annotations, the description covers purpose, usage, and sibling relationships. No output schema is needed, and the risk profile is fully annotated.

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

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

The schema provides a full description of the single 'key' parameter as 'Memory key to delete' (100% coverage). The description adds the qualifier 'previously stored' and 'by key' but no new format or semantic details beyond the schema 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 ('Delete') and resource ('memory by key'), clearly distinguishing it from sibling memory tools like 'remember' and 'recall'. It states exactly what the tool does without ambiguity.

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 when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also recommends pairing with 'remember and recall,' providing guidance on related 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=true and idempotentHint=true, so the safety profile is known. The description adds process details ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format') and clarifies the output ('single text blob ready to drop at site-root/llms.txt'), giving useful 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?

The description is three sentences, front-loaded with the purpose, then the process, then use cases. Every sentence earns its place, with no redundant phrasing 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?

The tool has only 2 simple parameters, rich annotations, and the description explicitly states the output format ('single text blob ready to drop at site-root/llms.txt'). Even without an output schema, the description fully covers what the agent needs to know for correct invocation and interpretation.

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

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

The input schema already covers both parameters with clear descriptions (url and max_links), achieving 100% schema description coverage. The tool description adds minimal parameter-specific detail—it mentions 'any URL' and 'key links' but doesn't elaborate on max_links or its default/limit, which the schema already documents. Thus, a baseline 3 is appropriate.

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

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

The description opens with a specific verb-object pair ('Generate a production-ready llms.txt file for any URL'), clearly naming the resource and scope. It also names the target consumers (AI crawlers) and the output format, making it distinct from all sibling tools, none of which generate llms.txt files.

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 concrete use cases, e.g., '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.' However, it doesn't explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by listing the returned fields (body, score, accepted), which goes beyond the structured annotations.

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

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

The description is two concise sentences, the first stating the core purpose and the second summarizing the returned data. It is front-loaded and every word 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?

This is a simple read-only tool with complete schema coverage and an output schema present. The description covers purpose and key return fields, which is sufficient for the tool's complexity. It could mention error cases or rate limits, but these are not critical given the annotations and schema.

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

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

The input schema descriptions cover all three parameters (100% coverage), so the schema already provides the necessary meaning. The description's 'by ID' adds no semantic value beyond the schema's explanation of question_id, so the baseline 3 applies.

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

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

The description clearly states the tool fetches answers for a specific StackExchange question by ID. The verb 'Get' plus the resource 'answers' and the scoping 'specific question by ID' make the purpose unambiguous and distinguish it from sibling search tools.

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

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

The description implies usage when the user already has a question ID, providing clear context. However, it does not explicitly exclude alternatives or mention when to use e.g. search_questions to first find an ID, so it falls short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description need not repeat safety. It adds useful behavioral context: the exact return fields ('title, score, answer count, whether answered, view count, tags, and link') and the tag-combination syntax, which is 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 front-loaded with the core purpose, followed by examples, return format, and a contrast with a sibling. Every sentence contributes unique value—no filler, no repetition of schema details already covered. It is appropriately sized for the tool's complexity.

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

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

Given there is no output schema, the description compensates by listing the return fields and the follow-up action (call get_answers). Combined with rich annotations and a fully described schema, the description is complete enough for an agent to invoke the tool correctly without guessing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mentions of sorting ('votes or recency') and tag combining (';') are already present in the schema's property descriptions. No additional parameter-level meaning is added beyond the schema, so the score remains at the baseline.

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

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

The description clearly states a specific action ('Browse questions by TAG') and enumerates use cases ('top questions tagged <tag>', 'trending <tag> questions this week/month'). It explicitly distinguishes from search_questions, making the purpose unambiguous.

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

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

The description explicitly names the alternative tool (search_questions) and explains the difference (keyword-based vs tag-based). It also provides concrete query examples and guidance to call get_answers for reading answers, which clarifies when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds value by enumerating the return fields (id, type, params, created_at, last_fired_at, fire_count), which is especially useful given there is no output schema. It does not add context about auth or rate limits, but the tool is simple and the annotations are strong.

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: the first states the purpose and return fields, the second gives usage guidance. Every word earns its place, with no repetition or filler. It is front-loaded with the most critical information.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it covers what the tool does, what it returns, and when to use it. The only missing detail is the include_inactive parameter, but that is fully documented in the schema, so the description does not need to repeat 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?

The input schema has 100% coverage for its single optional parameter (include_inactive) with a clear description. The tool description does not mention the parameter at all, so it does not add meaning beyond the schema. However, since the schema already fully explains the parameter, a baseline score of 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' This clearly distinguishes it from sibling tools like subscribe and unsubscribe, which perform mutating operations. It also specifies the scope ('active subscriptions') and names the returned fields, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance relative to the sibling subscribe and unsubscribe tools, and implies the alternatives without ambiguity.

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

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

Annotations are minimal (all false), but the description discloses rate limiting (5/day), cost (free, no quota), and the claim_token lifecycle. It also explains that feedback goes to a human team reading digests daily, adding meaningful behavioral context beyond the structured annotations.

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

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

Although the description is long, every sentence is information-dense and earns its place. It is front-loaded with the core purpose, followed by usage, exclusions, follow-up mechanics, and constraints, with no fluff or repetition.

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

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

The description covers the main use cases, which tools it applies to, the claim_token return and reuse, rate limits, and the human workflow. Even without an output schema, it explains what a user gets back (claim_token) and how to use it later, making it complete for this tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the claim_token flow (pass it back later) and clarifying that message should describe the issue in terms of Pipeworx tools, not paste end-user prompts. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb phrase, 'Tell the Pipeworx team something is broken, missing, or needs to exist,' naming the resource and action. It distinguishes the tool from all sibling tools by focusing on feedback submission rather than research, visibility checks, or subscriptions.

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

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

The description gives explicit 'Use when' criteria for bug, feature, data_gap, and praise, and provides a clear exclusion for tools from other MCP servers. It also tells users how to follow up with a claim_token and notes the daily rate limit.

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, idempotent, and non-destructive, but the description adds valuable context: it is self-aggregating, derived from CF analytics-engine, contains no PII (only pack/tool/count), and is cached for 5 minutes to 1 hour depending on the window. These details go beyond annotations and fully disclose 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 well-structured and front-loaded with the core output, followed by a concise numbered list of use cases and a brief technical note. Every sentence adds value, and the length is appropriate for the tool's richness.

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

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

Despite lacking an output schema, the description fully specifies the return contents (top tools, top packs, total call volume, and (pack, tool, count) tuples), the caching behavior, and the absence of PII. With only one optional parameter fully documented, this is complete for an agent to use the tool correctly.

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

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

The schema covers 100% of parameters, including a detailed enum description explaining the trade-off between shorter and longer windows. The tool description merely repeats the window options without adding new semantic meaning, so it does not go beyond what the schema already provides.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume over a recent window, aggregating what other AI agents are calling. It distinguishes itself from siblings by focusing on real-time agent usage trends rather than static discovery or recent changes.

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

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

The description provides explicit use cases with numbered examples (discovering hot data sources, confirming canonical tools, aligning use cases). It does not state when not to use it or name alternative tools, but the guidance is specific enough to help an agent decide when to invoke 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 and non-destructive, but the description adds significant behavioral context: the >3pp partition threshold that emits BUY/SELL EVERY LEG signals, the ≥0.30 Jaccard similarity gate, the >20% placeholder filter returning null, and the fill-check logic that warns 'do not trade it' when realizable edge is ≤0 at 1000 shares/leg.

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

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

The description is long but each paragraph has a distinct purpose and the main action is front-loaded in the first sentence. Paragraph breaks aid skimming, yet some sections are quite dense (e.g., the fill-check explanation) and could be tightened without losing value.

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

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

With no output schema, the description fully specifies the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and the partition_check object. It covers all parameter modes, edge cases, and the interaction with fill risk, making it a complete operational guide.

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 rich semantics beyond names: event accepts slugs or full URLs and walks child markets, topic takes seed questions and runs cross-event comparisons. Concrete examples for both parameters ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') make the invocation clear.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the three invocation modes (trending, event, topic) and separates this tool from siblings like polymarket_fill_risk and polymarket_edge_tracker.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', event mode for a specific market, topic mode for cross-event scans. It also explains why topic mode catches temporal patterns missed by single-event, and points to an alternative: 'For custom sizing use polymarket_fill_risk.'

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

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

Even with annotations (readOnlyHint, idempotentHint, etc.), the description adds substantial behavioral detail: caching at KV level for 1h, how filters can empty segments, diagnostic output (with funnel counters and filter_skips), and the rationale for excluding Fed bets. It also clarifies that partition parent-level kelly_fraction_half is always 0, which is critical non-obvious 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 long but well-structured with bolded sections, enumerated model families, and parenthetical details. It is front-loaded with the core purpose and then expands into necessary specifics. While verbose, 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?

Despite having no output schema, the description fully specifies the response top-level structure (by_segment), the contents of each segment, diagnostics, and edge fields (edge_pp_net, kelly_fraction, etc.). It also covers filtering behavior and caveats like the 24h-move warning, making it self-contained for an agent 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 the baseline is 3. The description adds value by grouping knobs into 'TRADEABLE-EDGE KNOBS' and explaining why min_partition_leg_kelly exists (parent-level Kelly is 0 for partition arbs, so min_kelly cannot filter them). This goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also names the three response segments and explains the tool's purpose ('what should I bet on today'), clearly distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the intended use case: agents discover opportunities without paging hundreds of markets, and it describes the tradeable-edge knobs. However, it does not name alternative tools or provide explicit 'when not to use' guidance, so it falls short of full differentiation.

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

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

The description adds substantial behavioral context beyond the annotations: history depth is bounded by a 60-day TTL, snapshots are only recorded on cache-miss causing gaps, and decay is computed from daily closes rather than intraday. This goes far beyond the readOnly/idempotent hints and gives the agent a clear safety and operational picture.

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

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

The description is well-structured with headings for Args, RESPONSE, and LIMITS. Every sentence adds necessary information, from the core question to response field definitions to operational constraints. Despite its length, it is dense and scannable, with no redundant filler.

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

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

With no output schema, the description fully compensates by explaining the return structure: tracked[], expired[], and snapshot_dates[], including field meanings and the significance of expiration lifespans. It also covers limits and operational quirks, making the tool's behavior comprehensive for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'Args' section largely restates what the schema already provides (lookback, default, window family), adding only minimal context like 'snapshot family.' It does not materially enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling `polymarket_edges` tool by clarifying it is built from snapshots, making it a distinct analytical layer.

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

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

The description provides clear context for when to use the tool: when you need to know edge persistence and decay, with the example of fresh vs. old wide edges. It does not explicitly state when not to use it or name alternative tools, but the context is strong enough to guide selection.

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

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

Annotations already mark the tool as read-only and non-destructive; the description adds deep behavioral detail: it walks the order-book ladder, returns specific fill metrics, and discloses that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and contains no filler, but its long single-flow structure with dense mode specifications makes it harder to scan. It would benefit from brief formatting, though every sentence contributes useful information.

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

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

With no output schema, the description thoroughly enumerates return fields for both modes (verdict, capture_ratio, thin_legs, forced_directional_risk, etc.) and explains why the tool matters operationally. It is complete for a complex two-mode 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%, but the description adds substantial meaning beyond the property descriptions. It explains the dual interpretation of size_usd (max spend vs target proceeds vs settlement notional), clarifies basket-side auto-detection, and notes per-leg $1 payoff. This goes well 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 first sentence states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when theoretical overround is not capturable and warns about partial fills, giving both affirmative triggers and contextual warnings.

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

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

Even with annotations already indicating read-only and idempotent behavior, the description adds substantial transparency. It details the response structure (leg-by-leg prices, top_spreads_pp), explains the two distinct compatibility_warning scenarios, defines temporal_alignment and its implications, and describes the skipped_cross_type/subtype counters. This goes far beyond the annotations and gives the agent a clear mental model of how the tool behaves and fails.

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: one-sentence summary, two modes, response fields, safety fields, and a caveat. It uses typographic emphasis (uppercase, quotes) to separate sections. Every sentence contributes information; there is no filler. However, it could be slightly more condensed, as the safety field explanations are detailed enough to be a separate reference document.

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

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

The tool has no output schema, so the description shoulders the responsibility of explaining what the agent will get back. It thoroughly covers the output fields, their semantics, and the conditions under which the spread is valid or meaningless. It also addresses edge cases like non-equivalent bet shapes and temporal misalignment. Given the tool's complexity, the description is remarkably complete.

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

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

The input schema already provides 100% coverage with examples for all three parameters. The description adds value by explaining the interplay between params: explicit ticker/slug overrides the topic-mapped side, and the topic list is elaborated with the exact shortcut names. This inter-parameter relationship is not present in the schema, so the description adds meaningful context beyond the baseline.

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

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

The description opens with a specific and clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately identifies the tool's unique function (cross-venue comparison) and distinguishes it from siblings like polymarket_arbitrage. The two modes (topic shortcuts vs explicit ticker/slug) further clarify the exact resource scope.

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

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

The description explains when to use each mode: 'topic' for pre-mapped shortcuts, and explicit event ticker/slug for custom pairings. It also provides important caveats—pre-mapped topics often return compatibility_warning and are not necessarily tradeable. However, it does not explicitly mention alternative tools or when not to use this tool in favor of a sibling, so it falls slightly short of a 5.

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

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

Annotations already declare safe read-only, idempotent, non-destructive hints. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key argument (lists all keys). This goes beyond annotations by explaining visibility and listing behavior, which is important for the agent to understand.

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

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

The description is three sentences, front-loaded with the core function. Every sentence adds value: the first explains the main action, the second provides use cases, and the third explains scoping and pairing with remember/forget. No wasted words.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers all necessary aspects: what it retrieves, how to list, scoping, and relationship to sibling tools. It is complete given the low complexity and rich annotations.

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

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

The schema already provides 100% coverage of the single parameter ('key') with a description and examples, so the baseline is 3. The description adds examples of what keys might contain (ticker, address, notes) but does not add major new semantics beyond the schema. It complements but does not significantly extend the schema's meaning.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses a specific verb and resource, and distinguishes itself from siblings by explicitly referencing 'remember' and 'forget' as complementary tools. It also provides concrete examples of stored context (target ticker, address, research notes), 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?

The description says 'Use to look up context the agent stored earlier' and provides scenarios (user's target ticker, address, prior research notes). It also implies when to use versus alternatives by framing it as a memory lookup. It does not explicitly mention alternative tools to avoid using, but the context is clear enough for a memory retrieval tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds vital behavioral context: it explains the mark_read side effect (flags events read so future calls return only newer ones), the source of events (evaluator-written persisted feed), and the inclusion of raw payloads. It does not contradict any annotation and substantially enriches the behavioral model.

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 every sentence earns its place: core purpose, return payload details, filtering and mark_read behavior, and the alternative HTTP endpoint. The key action is front-loaded, and there is 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?

Given five optional parameters, no output schema, and helpful annotations, the description covers the essential aspects: what events are returned, how to filter, the mark_read state change, polling suitability, and an alternative access path. It is sufficiently complete for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving an example for type (e.g., 'sec_8k'), clarifying 'since' as ISO timestamp, and explaining the interaction between mark_read and subsequent polling. This goes slightly beyond the schema's per-parameter descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly states the verb, resource, and scope. It further specifies what each event carries and distinguishes itself from sibling tools by focusing on alerts/events rather than subscriptions or changes.

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

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

The description provides clear context by stating that polling works fine and offers an explicit alternative: the same feed is available via HTTP for scripts/dashboards. However, it does not explicitly name alternative tools or give exclusions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds valuable behavioral details: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO patent data with a known sunset date and soft-failure mode, and returns structured changes with citation URIs. 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 more verbose than ideal, but it is front-loaded with user intent phrases and efficiently packs source details, fallback logic, parameter formats, return shape, and an alternative tool. Every sentence contributes useful context, though the length could be trimmed slightly without losing value.

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

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

With no output schema, the description adequately explains the return structure: grouped changes by source, total_changes count, and citation URIs. It also covers source-specific caveats (USPTO soft-fail, GNews fallback) and the `since` parameter's formats, making the tool self-contained for agent invocation.

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

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

Schema coverage is 100% and includes descriptions for all three parameters. The description reinforces the `since` parameter's accepted formats and typical monitoring values, but this largely duplicates schema content. It does not add significant new meaning 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 clearly states the tool provides a change feed for a company over a time window, with specific verbs like 'What's new' and 'updates on'. It distinguishes itself from sibling entity_profile by explicitly noting that entity_profile should be used for static profile data instead.

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

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

The description gives explicit usage examples ('What's new with X', 'latest on Y') and provides a clear alternative: 'Use entity_profile instead when you want the static profile...'. It also explains the fallback behavior between GDELT and GNews, helping the agent decide when this tool is appropriate.

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

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

Beyond annotations (idempotent, non-destructive), the description adds scoping by identifier, persistence duration for anonymous sessions (24h), and authenticated persistent memory. This is valuable behavioral context not in the annotations.

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

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

Three sentences, front-loaded with the primary purpose, then usage, then persistence/related tools. Every sentence earns its place with no filler.

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

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

For a simple key-value storage tool, the description fully covers purpose, when to use, persistence characteristics, and related tools. Annotations and schema cover the rest, so no gaps remain.

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

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

Schema descriptions already cover key/value with examples, so baseline is 3. Description adds slight value by reinforcing key-value pair semantics and stating value can be 'any text', which complements the schema without redundancy.

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

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

The description explicitly states 'Save data the agent will need to reuse later' with concrete examples (ticker, address, preference). It distinguishes from siblings by naming recall (retrieve) and forget (delete).

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

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

Provides explicit 'Use when' guidance with examples and clarifies persistence semantics (authenticated vs anonymous). Also tells the agent to pair with recall and forget, giving clear context for alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavior: accepts various input forms, labels identifiers with source, explicitly reports unresolved identifiers, gracefully degrades when GLEIF/OpenFIGI unavailable, and cascades through multiple internal endpoints. This goes well beyond the structured annotations.

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

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

The description is moderately sized but well-structured, opening with concrete example queries followed by a clear purpose statement and then type-specific details. It front-loads the key usage directive ('Use FIRST...') and avoids redundancy, though it could be tightened slightly without losing essential caveats like graceful degradation.

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 two-entity-type lookup tool with no output schema, the description covers input formats, output identifiers (CIK, LEI, FIGI, RxCUI), source attribution, unresolved handling, and failure behavior. It explains the internal cascade and why this replaces multiple manual lookups. The lack of exact output schema is mitigated by this rich prose.

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

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

Both parameters are fully described in the schema, so baseline is 3. The description adds context by elaborating on value formats (e.g., 'AAPL' vs '0000320193'), what each type returns, and the behavior around unresolved identifiers. This enriches the parameter semantics beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with a specific verb ('resolve') and resource (names/IDs). It distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID' and supports two entity types with specific outputs, differentiating it from sibling tools like entity_profile or compare_entities.

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

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

It explicitly tells the agent to 'Use FIRST whenever you have a name but need an ID' and gives example queries. It also notes that using resolve_entity replaces 2-3 manual lookups, implying it should be preferred over direct endpoint calls. However, it doesn't name specific alternative tools or exclusion cases, so 'when-not-to-use' is implicit.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value beyond that by disclosing that it probes with ai_visibility_check, ranks by score, and returns a structured result with score, confidence, and signal density. This gives operational 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 three sentences: first states the core function, second explains the mechanism, third provides a use case and output summary. No wasted words; every sentence adds distinct value and the main purpose is front-loaded.

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

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

The tool is a composite read-only operation with no output schema, so the description carries the burden of explaining what it returns, which it does (ranked list, score, confidence, signal density). The schema covers all parameters and constraints, and the annotations cover safety. The description is sufficient for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100% with each parameter described in detail, so the baseline is 3. The description adds minimal semantic value beyond the schema—it mentions the first entity as subject and calls ai_visibility_check, but these are already in the schema. No meaningful additional parameter explanation is needed.

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 and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the single-entity sibling ai_visibility_check by emphasizing the multi-entity comparison and ranking behavior, and it ties to a concrete use case with an example.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' and an example. However, it does not explicitly name alternatives or state when not to use it (e.g., for a single entity). The sibling list and description imply multi-entity use, but the guidance is not fully explicit about exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds key behavioral context: composite fan-out across services, graceful degradation on partial failures, a 5-30s latency warning for first bundlephobia measurement, and the sources_failed field behavior. This exceeds 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?

Description is dense but efficiently structured: purpose front-loaded, then usage, return summary, ecosystem limitation, and failure behavior. Every sentence provides distinct value without waste; length is justified by the composite nature of the tool.

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

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

No output schema exists, yet the description enumerates the full return shape: summary block fields, per-advisory detail, links, alternative versions. It also covers error/timeout behavior, ecosystem constraints, and performance expectations, making the tool fully usable without additional documentation.

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

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

Input schema coverage is 100% with both parameters well-documented (package name with scoped support, optional version with default). The description adds minimal parameter-specific semantics beyond the schema, though it does reinforce through examples. Baseline 3 is appropriate when schema fully covers parameter meaning.

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

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

The description opens with a specific composite check: 'should I add this npm package to my project' in ONE call, and details the exact data sources (deps.dev and bundlephobia) and the data categories returned. It clearly distinguishes itself from other tools by specifying NPM-only scope and contrasting with deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives an exclusion/alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns specific fields and supports any StackExchange site, but it does not disclose rate limits, authentication nuances, or pagination behavior. It adds some 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 a single sentence that is front-loaded with the action ('Search for questions') and immediately provides scope and return fields. Every word contributes value with no redundancy or vague filler.

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

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

The tool has an output schema, so return values are already structured. The description covers purpose, scope, and key output fields. Combined with rich annotations and complete parameter descriptions, it is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description does not add additional parameter-specific semantics beyond stating the return fields, which is implicitly tied to the query parameter but not explicitly. Baseline 3 is appropriate because the schema carries the burden.

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

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

The description uses the specific verb 'Search', identifies the resource as 'questions', and scopes to 'StackOverflow or any StackExchange site'. It also lists the return fields (title, body, score, answer count, tags, link), which clearly distinguishes it from sibling tools like get_answers or list_questions_by_tag.

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

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

The description clearly indicates when to use the tool (searching for questions across StackExchange sites), but it does not explicitly state when not to use it or mention alternatives. Sibling tools exist but are not referenced in the description, so it lacks 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?

The description goes well beyond annotations by disclosing return format (passages with offsets and similarity scores), the embedding model and algorithm (BGE-base-en + cosine over 500-char windows), and input limits (200K chars with truncation flagged). This adds substantial behavioral context not available from annotations alone.

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

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

Three sentences with front-loaded purpose, followed by usage guidance and technical specifics. No redundancy or filler; every sentence contributes meaningful information.

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

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

Despite lacking an output schema, the description explains the return values (passages, offsets, similarity scores), input constraints, and embedding details. For a tool with moderate complexity, this is thorough 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 meaning by clarifying the 'text' parameter should be content already fetched (e.g., SEC filing, article) and explains that 'query' is a natural-language request. It also indirectly describes the output's relationship to 'limit' (top-N passages). This extra context elevates 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 performs semantic search inside a provided text ('Semantic search INSIDE a fetched record'), with a specific verb, resource, and scope. It distinguishes from siblings by emphasizing it operates on already-fetched content rather than fetching or grounding, and references ask_pipeworx_grounded as a complement.

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 when-to-use guidance is given: 'Use when the record is too big to cram into the prompt.' It also names a specific sibling tool (ask_pipeworx_grounded) and explains how the two pair, providing clear context and an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds behavioral context by specifying return fields and cross-site support, which goes 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 two sentences, front-loaded with the action and return fields, and contains no redundant or vague wording.

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

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

The tool has a rich output schema and clear annotations, and the description covers purpose, return values, and site flexibility. A minor gap is not explicitly warning that user IDs are site-specific, though the schema's URL example implies this.

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% description coverage for parameters, so the baseline is 3. The description reinforces the numeric ID and default site, but adds no new parameter semantics beyond what the schema already provides.

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

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

The description begins with 'Look up a StackExchange user by numeric ID,' providing a specific verb, resource, and method. It also lists the return fields and clarifies that it works on any StackExchange site, distinguishing it from sibling tools like get_answers or search_questions.

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 implies when to use the tool — when you have a numeric StackExchange user ID and need profile information. It also mentions the default site, but it does not explicitly state alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool returns question counts and synonym info and can filter server-side (e.g., min_count when sort=popular). This is useful but does not go into deeper behavior like pagination, rate limits, or result formatting. With annotations doing the heavy lifting, a 3 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 three sentences: the first states the core function and variants, the second lists answerable questions, and the third shows two representative examples. It is front-loaded with the primary verb and resource, and every sentence earns its place. 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?

Despite having 7 parameters and no output schema, the description covers the main functionality, the types of queries it handles, and example invocations. It mentions question counts and synonym info, which hints at the return content. The annotations further fill safety context, making the description complete for this tool's complexity and schema richness.

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% description coverage across all 7 parameters, so the schema already documents each parameter clearly. The description reinforces the meaning of sort, inname, and tags by mentioning popularity, name fragments, and specific tags, and the examples illustrate parameter combinations. However, it adds little beyond what the schema already says, so the baseline of 3 is warranted.

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 'List or search StackOverflow / StackExchange tags' — a specific verb and resource. It then enumerates three distinct usage modes (popular tags, name-fragment matches, specific tag stats) and gives concrete example queries. This clearly distinguishes it from sibling tools like search_questions or list_questions_by_tag, which operate on questions rather than tags.

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 use cases by listing natural-language questions it answers ('most popular StackOverflow tags', 'how many questions are tagged X') and concrete examples. It implies when to use this tool (whenever you need tag-level statistics) but does not explicitly exclude alternatives or mention when not to use it. The context is clear enough, though explicit 'when not to use' guidance would push it to 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 annotations, the description discloses important behavioral details: OAuth requirement, persistent vs. non-persistent for anonymous/BYO, always-on feed, SMS phone verification and daily cap, and for webhook delivery (in the schema) auto-disable after 10 consecutive failures and one-time signing secret. These add meaningful context beyond readOnly/idempotent flags.

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

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

The description is dense but well-organized: purpose first, then supported types, then delivery channels. Every sentence contributes useful information, though the length is considerable. It remains efficient given the number of types and channels covered.

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

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

The description covers return value (subscription id), authentication requirements, delivery channels, restrictions (phone verification, cap), and feed access. Given the schema already details params and there is no output schema, the description is comprehensive for a tool of this complexity. It could reference siblings like unsubscribe, but the coverage is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds domain semantics for type values: sec_8k items meaning (e.g., '5.02' = officer change), polymarket_edge as cross-venue mispricings, fred_series as FRED observations. Delivery channels are also explained with examples. This adds interpretive value beyond the schema's structural descriptions.

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

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

The description opens with a specific action: 'Create a proactive monitoring subscription to a live-data event stream.' This clearly states the verb and resource, and distinguishes the tool from siblings like list_subscriptions and unsubscribe. It also immediately notes the returned value (subscription id), reinforcing its 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 explicitly states a prerequisite ('Requires a Pipeworx OAuth account') and notes that anonymous/BYO cannot persist subscriptions. It also provides delivery channel guidance, including how to pull the feed via recent_alerts or a registry endpoint. While it doesn't explicitly contrast with list_subscriptions/unsubscribe, the intended use case is evident from the context and sibling names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: output structure (category-bucketed example questions), the dynamic origin ('drawn from the live catalog of thousands of tools'), and the behavior of returning exact tool+argument shapes. It does not contradict annotations and enriches the safety profile.

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

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

The description is a single dense paragraph, front-loaded with example phrasings, then purpose, then output/usage. Every section earns its place, though the abundance of example queries makes it slightly longer than necessary. It is well-structured but could be trimmed modestly 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?

Given no output schema, the description thoroughly explains the return value: category-bucketed example questions with exact tool+argument shape, listing the categories explicitly. It also covers parameter usage, default behavior (full spread vs. focus), and the ideal usage scenario, 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 already provides 100% coverage for 'topic' with an explicit enum-like list. The description adds examples ('finance', 'pharma', 'betting') and clarifies the omission semantics ('Omit for a cross-category spread'), which complements the schema without repeating it.

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

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

The description opens with multiple example user intents ('What can I ask Pipeworx?', 'give me ideas') and states it is 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It clearly specifies the resource (example questions) and action (returns a categorized spread), and differentiates itself from sibling tools by mentioning meta-tools like ask_pipeworx and entity_profile.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also clarifies optional topic filtering ('pass topic to focus') and when to omit it for the full spread, giving clear contextual guidance without naming alternatives directly.

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

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

The description discloses ownership restrictions and the deactivation (not deletion) behavior, adding meaningful context beyond the annotations. It explains that historical events remain accessible via recent_alerts, which is valuable behavioral information.

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

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

Two sentences, front-loaded with the core action, followed by two key constraints. No redundant wording; 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 single-parameter mutation tool with robust annotations and schema, the description covers purpose, effect, ownership, and data retention. The absence of an output schema is acceptable as the tool's behavior is fully described.

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 id parameter is already well-documented as 'Subscription id (uuid) returned by subscribe.' The description merely says 'by id' without adding new semantic details, so the baseline of 3 applies.

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

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

The description opens with 'Cancel a subscription by id,' using a specific verb and resource, and clearly distinguishes this from sibling tools like subscribe and list_subscriptions. The action is unambiguous.

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

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

It provides clear context: ownership is enforced and the row is deactivated, not deleted. It also points to recent_alerts for historical events, implying an alternative. However, it doesn't explicitly state when to use this versus other tools or when not to use it.

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

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

Provides rich behavioral context beyond the readOnlyHint annotations: details two processing paths, defines each possible verdict, and clarifies that 'could_not_verify' does not count as evidence either way. This is exactly the kind of guidance that prevents an agent from misusing the tool.

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

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

The description is long but every sentence conveys essential information: examples lead, then use cases and behavior, then error semantics and performance benefits. It is well-structured and free of redundancy, making it appropriate for a tool of this complexity.

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

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

With no output schema, the description thoroughly covers what the tool returns (verdict, value, citation, reasoning), distinguishes error and unsupported outcomes, and explains the internal routing and the efficiency benefit. This is a complete and self-sufficient description for an agent.

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

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

Schema coverage is complete (100%), but the description adds meaningful semantics, especially for tolerance_pct, explaining its role in overriding inferred tolerances and offering a concrete recommendation (1–2 for hallucination detection). This goes beyond the basic schema 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 identifies the tool's function: natural-language claim verification against authoritative sources, with numerous example phrasings ('fact check', 'verify the claim that…'). It distinguishes itself from general Q&A tools by focusing on verifying factual claims and returning a verdict.

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

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

Explicitly states when to use ('Use whenever the agent needs to check whether something a user said is factually correct') and provides conditional logic for company-financial vs. other claims. However, it does not explicitly name alternative sibling tools or state 'when not to use', 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.