Statuspage

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

Annotations already declare read-only, idempotent, and open-world behavior. The description adds billing context (BYO key, direct payment to Anthropic), the free default model, and the return structure, which goes beyond annotations. It omits failure modes and rate limits.

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

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

Three sentences with no fluff. The description front-loads the main action, then covers models, billing, output, and use cases efficiently. 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 tool with no output schema, the description explains the per-model return structure (score, confidence, signals, raw_response) and combined view. It covers the default model, optional Anthropic integration, billing, and typical use cases, making it complete for selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the default model (Workers AI is free) and the billing implications of _apiKey, which supplement the schema's parameter descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence.

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 concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default vs optional model choice. It does not explicitly contrast with alternatives or state when not to use it.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavioral traits: it dynamically routes to 5,462 tools, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. These traits directly inform agent expectations and are not inferable 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?

The description is fairly long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Every sentence adds value, though some redundancy exists (repeated phrasing around 'use whenever...' and overlapping examples). For a tool with such broad scope, the length is largely justified.

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

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

Given the tool's complexity (a router over 5,462 tools) and the lack of an output schema, the description is remarkably complete. It covers use cases, trigger phrases, examples, alternatives, behavioral expectations (citations, speed), and account tier requirements. No critical gaps are apparent.

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

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

The input schema provides 100% coverage for all six parameters, each described as an alias for 'question'. The description does not add new parameter-level semantics beyond the schema, but it does provide contextual examples of valid questions. With full schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's core function: routing factual questions to thousands of verified sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning as the default entry point.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH'), trigger phrases ('what is', 'look up', etc.), and concrete examples. It also explicitly contrasts with alternatives ('use ask_pipeworx_grounded for a hallucination-resistant single answer', 'use deep_research for broad/multi-part questions'), making the decision boundary clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about the experimental nature, the fact that a candidate may be active and alter routing behavior, and that there is no fallback—it is a full working router. This goes beyond annotations but doesn't detail potential behavioral differences when a candidate is active.

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 and front-loaded with the beta purpose. It contains some redundancy (repeating 'identical' and the claim of matching ask_pipeworx exactly), but each sentence contributes useful information about the tool's status and behavior. Slightly trimmed would be ideal.

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 router tool with no output schema, the description gives sufficient context: it explains the tool's relationship to ask_pipeworx, its experimental edge, and the absence of a fallback. It references the same response shape as ask_pipeworx, which is adequate for agents familiar with the stable sibling, though it could detail response structure for standalone use.

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

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

Schema description coverage is 100%, so the schema fully documents the 'question' parameter and its aliases. The description adds no parameter-specific meaning, merely stating that arguments are the same as ask_pipeworx. This meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape, but with experimental routing improvements. It distinguishes itself from the sibling ask_pipeworx by emphasizing its beta status and live candidate testing.

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

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

Explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' This tells the agent when to choose this tool over the stable sibling and explains that results are compared against the stable router. It also notes that currently it matches ask_pipeworx exactly, providing a clear usage context.

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

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

Builds on the annotations by disclosing refusal reasons, return fields including verbatim evidence, and the extra LLM call cost. This goes far beyond the read-only/idempotent hints and gives a clear behavioral contract without contradicting annotations.

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

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

The description is four sentences long, dense but efficient, and front-loaded with the core purpose. Each sentence adds value, though the detailed refusal reason list could be seen as slightly lengthy; still well-structured.

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

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

Without an output schema, the description fully specifies the success and refusal return structures, plus the routing mechanism and use cases. This makes it self-contained for an agent to invoke correctly in high-stakes scenarios.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question.' The description does not add parameter-specific syntax or format details, but the schema already fully covers semantics, so the baseline of 3 applies.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers using ONLY tool result content. It distinguishes from the sibling ask_pipeworx by specifying the same routing but grounded extraction, giving a specific verb+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?

Explicitly instructs when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides a direct alternative: 'prefer ask_pipeworx for casual lookups,' naming the specific sibling tool and the trade-off.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral context: low-confidence short-circuit behavior, fallback handling for GDELT 429s, wide-spread illiquidity warnings, cancellation rule parsing, and both blocking failure routes. This significantly 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?

The description is long but exceptionally well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose. Every section adds unique information, though its sheer length prevents a perfect conciseness score.

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

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

Given no output schema, the description thoroughly covers return shapes (market, analysis, evidence), resolver contract, parent_event extraction, news fallback fields, and safety mechanisms. It anticipates edge cases like closed markets, low-confidence matches, and cancellation rules – making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description elevates this by giving concrete input examples (slug, URL, question text), explaining depth options with source-count implications, and detailing include_raw's tradeoff between response size and raw payloads – all valuable beyond the schema definitions.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb, resource, and outcome. It further clarifies its niche with 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', making it distinct from sibling tools like validate_claim or polymarket_edges.

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

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

The description explicitly states when to use the tool via the 'Use for' examples, and provides multiple concrete fan-out examples for different bet types (BTC, Fed, Hormuz, Yankees WS, etc.). It does not, however, mention when not to use it or contrast with specific 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, but the description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradiction with annotations.

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

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

Though moderately long, every sentence earns its place: starts with actionable trigger patterns, then quickly covers type-specific data, sorting behavior, and return format. No redundancy or fluff; information-dense and front-loaded with usage cues.

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

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

Given no output schema, the description adequately explains what is returned (paired data + citation URIs) and how results are ordered. It fully covers input requirements, data sources, and behavioral nuances, making it complete for an agent to select and invoke correctly for comparison queries.

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 description adds significant meaning: explains what type='company' pulls (10-K financials) versus type='drug' (FAERS counts, FDA approvals, trials), and clarifies the values array format (tickers/CIKs or drug names, 2–5 items). It also notes the 'ONE parallel call' efficiency, going beyond schema basics.

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

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

Description uses specific verb 'compare' and resource 'companies or drugs', clearly stating a side-by-side comparison of 2–5 entities in one parallel call. It distinguishes from sibling tools by explicitly noting it replaces sequential single-pack lookups, making its unique role clear.

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

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

Provides explicit trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and a strong directive: 'ALWAYS PREFER over sequential single-pack lookups'. It also distinguishes between company and drug types, clarifying when each is used.

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

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

Annotations already mark it read-only/idempotent/non-destructive; the description adds substantial behavioral detail: account/paywall requirements, parallel facet routing, explicit gaps[] for unanswered facets, no invention of answers, semantic excerpting, and reliable citation resolution. 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 lengthy but well-structured and front-loads the critical account requirement and the main alternative. Every sentence contributes functional context, though some trimming could improve skimmability.

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

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

For a complex tool with no output schema, the description covers the full return packet structure, timing expectations, limitation behavior (gaps), and interplay with auth/paid tiers. This provides a complete operational picture 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 already documents both parameters with 100% coverage; the description goes beyond by clarifying the practical meaning of depth (hops, gap recovery, contradiction scans) and affirming that question can be broad/multi-part. It adds behavioral nuance but doesn't introduce new parameters.

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

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

The description names a specific action ('grounded multi-source research') and a concrete resource ('Pipeworx's 1419 STRUCTURED data sources'), explicitly contrasting with open-web search and sibling ask_pipeworx. It clearly distinguishes this tool's scope from single-lookup and news-oriented tools.

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

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

It states exactly when to use deep_research ('broad/multi-part questions over structured data') and when to prefer ask_pipeworx (single lookup, breaking news, colloquial current events, or when not signed in). This provides both positive and negative selection criteria with alternative tool 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=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: returns top-N relevant tools, includes full input schemas with curated examples, and results are ready to call directly without a second schema lookup. This goes beyond annotations but does not fully detail pagination or ranking 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 somewhat long due to the domain list, but each sentence serves a distinct purpose: purpose, usage, output format, and strategic guidance. The structure is front-loaded with the core verb and resource, and the domain list, while extensive, provides quick context for the user. Not maximally concise, but 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?

For a discovery tool with no output schema, the description fully covers purpose, usage, return value (top-N tools with names, descriptions, schemas), and how to use the results (ready to call directly). It is self-contained and adequate for an agent to know 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 defined (query, q, task, limit, search, description). The description mentions 'top-N' and 'describing the data or task' but does not add significant meaning beyond the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and action (find/discover), and the domain list (SEC filings, FDA drugs, etc.) gives concrete scope. It distinguishes itself from siblings by being a meta-tool for discovering other tools, unlike task-specific siblings like deep_research or statuspage_check.

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 it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and implies not to use it when you already know the specific tool or need a direct answer.

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

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

Annotations already mark readOnly=idempotent, but the description adds substantial behavioral detail: multi-source fan-out across SEC, XBRL, USPTO, GDELT/GNews, GLEIF; patent API sunset soft-fail; GDELT→GNews fallback; and the name-not-supported limitation. This goes well beyond the annotation 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 highly organized: examples, core promise, source list, return fields, and constraints. Every sentence contributes operational meaning, and the key message is front-loaded. 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?

With no output schema, the description carries full responsibility for explaining returns, and it enumerates each field (cik, recent_filings with URIs, fundamentals, patents, news, LEI). It also covers edge cases (patent API sunset, name unsupported) and alternatives, making it self-contained for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193') and reiterating the 'names not supported' constraint, reinforcing what the schema already states. This modestly exceeds 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 concrete user request examples then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly differentiates from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions resolve_entity for name-only queries.

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

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

Usage is explicitly specified: use when the user asks for a holistic view, and prefer over chaining smaller lookups. It also gives a when-not case: if only a name is available, use resolve_entity first. This provides clear alternatives and conditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context beyond these by clarifying that it deletes a 'previously stored memory by key' and that it can be used to 'clear sensitive data.' This communicates the irreversible nature and the specific resource affected, which is useful for the agent.

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

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

The description is three sentences, each carrying distinct value: the action, the use cases, and the companion tools. It is front-loaded with the primary instruction and contains no filler or redundant restatement of the tool name.

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

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

For a simple single-parameter tool with clear annotations (destructive, idempotent), the description fully covers the operation, the circumstances for use, and the relationship to sibling tools. No output schema exists, so no return-value description is needed. The description is complete and appropriately scoped.

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 100% coverage for the only parameter 'key' with the description 'Memory key to delete.' The tool description only repeats 'by key' without adding extra detail about key format, domain values, or constraints. Since the schema already fully explains the parameter, the description adds no additional semantic value.

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

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

The description opens with a specific verb-resource pair: 'Delete a previously stored memory by key.' It clearly identifies the action (delete) and target (memory by key). The sibling context with 'remember' and 'recall' makes its role in a memory system evident, distinguishing it from storage and retrieval tools.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also says 'Pair with remember and recall,' pointing to complementary tools. However, it does not explicitly state when not to use it (e.g., for retrieval use recall), so it lacks a full exclusionary guideline.

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

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

The description transparently explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies that the output is a text blob, not an actual file write. This complements the annotations (readOnlyHint=true, idempotentHint=true) and adds useful behavioral context beyond them.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. It efficiently includes the output format, use cases, and key actions without unnecessary fluff. Every sentence adds value.

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

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

For a simple tool with two well-documented parameters and strong annotations, the description covers all essential aspects: what it does, how it works, what output to expect, and when to use it. No output schema is present, but the description adequately explains the return value as 'a single text blob ready to drop at site-root/llms.txt.'

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 descriptions for both parameters. The description adds some context by mentioning 'any URL' and the output includes links (relevant to max_links), but it does not elaborate on parameter specifics beyond what the schema states. Thus, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the verb (generate), resource (llms.txt file), and context (AI crawlers). This distinguishes it from siblings like 'scan_competitor_ai_presence' or 'ai_visibility_check', which focus on checking visibility rather than creating the file.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It clearly indicates when to use the tool, though it does not explicitly mention any exclusions or alternative 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 destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying the return fields ('Returns id, type, params, created_at, last_fired_at, fire_count for each') and scoping to 'the caller's active subscriptions,' which goes beyond the annotations. It doesn't describe pagination or ordering, but for a simple list tool this is adequate.

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. It is front-loaded with the key action and outcome, with zero wasted words.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description adequately covers purpose, usage, and return fields. It compensates for the lack of an output schema by explicitly listing the returned fields and gives a clear context for use. No significant 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 coverage is 100% with the only parameter 'include_inactive' described as 'Include cancelled subscriptions in the response (default false).' The tool description adds no parameter-specific details beyond this, so the baseline of 3 applies. The description's mention of 'active subscriptions' implicitly aligns with the parameter but doesn't add new insight.

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 'List the caller's active subscriptions' and enumerates returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling subscribe/unsubscribe tools by focusing on a read-only listing operation and providing a concrete use case.

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 to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context on when to invoke the tool, contrasting with the actions of adding or cancelling subscriptions. Though it doesn't name siblings like subscribe/unsubscribe explicitly, the usage guidance is explicit 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?

With all annotations set to false, the description must carry the transparency burden. It discloses meaningful behavioral details beyond the annotations: rate-limited to 5 per identifier per day, free (doesn't count against tool-call quota), and the team reads digests daily with signal affecting roadmap. It does not describe response behavior (e.g., no confirmation), but the core operational constraints are clearly stated. This adds substantial context over the empty annotation hints, though not exhaustive.

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

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

The description is longer than typical (about 120 words) but every sentence serves a unique purpose: purpose, usage scenarios, exclusion, clarification, message formatting, motivational context, and operational constraints. It is front-loaded with the core action and then adds nuanced usage details. It could be slightly tightened, but the structure is logical and efficient for the tool's complexity.

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

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

The tool has 3 parameters, one nested object, and no output schema. The description covers all essential context: when to use, what categories exist, how to frame feedback, what not to include, rate limits, and quota implications. For a feedback submission tool, this is fully complete; no return value explanation is necessary, and the description preempts common misuse scenarios.

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 input schema already fully documents each parameter (type enum values, context object fields, message length limit). The description reinforces this by mapping 'type' values to real-world meanings and advising users to be specific, but it does not add new semantic information beyond what the schema provides. Per the calibration baseline, a score of 3 is appropriate.

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

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

The description opens with a clear, specific statement of purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It defines the four feedback categories (bug, feature, data_gap, praise) and explicitly differentiates from other MCP servers by stating it only handles tools served by this Pipeworx connection. This makes the tool's role unambiguous and fully distinguishes it from sibling tools.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: feedback for tools from different MCP servers should be filed with that server instead. Additionally, it instructs users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, offering practical usage 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 indicate the tool is read-only, idempotent, and non-destructive, so the description carries a lighter burden. It adds valuable context beyond annotations by explaining the data source (CF analytics-engine), privacy (no PII), output format (pack, tool, count), and caching behavior (5min-1h depending on window).

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

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

The description is efficiently structured, starting with a clear one-sentence summary, followed by the return payload and a bulleted list of use cases. Every sentence adds value without unnecessary verbosity, making it concise yet informative.

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

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

For a simple one-parameter tool with no output schema, the description fully covers what is returned (top tools, packs, call volume), the data source, privacy, and caching. Together with the rich annotations, the description provides complete context 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?

Schema coverage is 100%, and the schema already fully describes the window parameter with enum values and explanations. The description reiterates the window semantics but adds no new meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: it returns the top tools, top packs, and total call volume over a recent window. The phrase 'What other AI agents are calling on Pipeworx right now' gives a specific, distinct purpose that differentiates it from siblings like discover_tools, which is about discovering available tools rather than trending usage.

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 lists three concrete use cases, such as discovering hot data sources and confirming a canonical tool. This provides clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Beyond the readOnlyHint, the description discloses important behavioral details: the Jaccard similarity anchor, partition filtering with placeholder fraction thresholds, the fill check against live CLOB depth, and explicit warnings like 'realizable_edge_pp <= 0 means ... do not trade it.' This is far more than 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 and front-loaded with the purpose, and every sentence adds value. However, it is a long monolithic paragraph covering many details; clearer sectioning (modes, algorithm, output) would improve scannability without losing information.

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

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

Even though there is no output schema, the description fully explains the response structure, including opportunities[] fields, partition_check object, and the null signal case. It also covers edge cases (thin legs, realizable edge) and references related tools, making it complete for a complex arbitrage tool.

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

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

The schema already covers both parameters, but the description adds rich semantics: concrete examples (fed-decision-may-2026), explanations of what each mode does, and a note that full Polymarket URLs are accepted. This goes well beyond the baseline 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 first sentence clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It then describes the three invocation modes (no args, event, topic), making it distinct from sibling tools like polymarket_edges.

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

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

The description gives explicit guidance for when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It also points users to polymarket_fill_risk for custom sizing, clearly indicating an alternative 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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint), detailing the three response segments, per-opportunity fields, diagnostics for empty segments, and the 1-hour cache at the KV level. It explains edge computation, slippage handling, and why Fed bets are excluded, offering deep insight into the tool's 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 lengthy but well-structured with explicit section markers like 'FIVE MODEL FAMILIES', 'EVERY OPPORTUNITY', 'TRADEABLE-EDGE KNOBS', and 'RESPONSE TOP-LEVEL'. This organization makes it navigable, and the density is justified given the tool's complexity, though it could be tightened.

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

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

Without an output schema, the description thoroughly documents the response structure, including by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also explains why a segment might be empty, ensuring callers understand the tool's behavior even in edge cases.

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 meaningful context: it names the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and explains how they filter opportunities. It also clarifies that min_kelly does not apply to partition overround, a nuance not present in the schema, providing genuine added value.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today', which is a specific, actionable use case. This distinguishes it from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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

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

The description provides context on when to use the tool—'built for what should I bet on today'—and notes that agents avoid paging hundreds of markets. However, it does not explicitly mention alternative tools or scenarios where another tool would be more appropriate, so it lacks direct exclusion 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=true and idempotentHint=true, but the description adds significant behavioral context beyond these: snapshots are written only on cache-miss, history is bounded by a 60-day TTL, decay is based on daily closes rather than intraday, and expired entries are 'closed, resolved, or arbed away.' This gives the agent essential operational nuances that annotations cannot convey.

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

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

The description is long but well-structured with clear Args, RESPONSE, and LIMITS sections, making it scannable and useful. Every sentence adds substantive value—none are filler. However, it is quite verbose, and a slight tightening would improve terseness without losing fidelity.

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 explains the response structure (tracked, expired, snapshot_dates) and critical limitations (TTL, cache-miss gaps, daily close basis). It also clarifies interpretation nuances like signed edge_pp_net values and trend categories. This is a model of completeness for a complex telemetry tool.

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

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

The schema already fully documents both parameters with descriptions (days lookback with defaults and clamps, window family with options). The description reiterates these defaults and adds minor phrasing ('snapshot family') but does not materially enrich parameter semantics beyond the schema. Since schema coverage is 100%, a 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 clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and shrinking, which differentiates it from the sibling polymarket_edges tool that likely provides current edges. The verb 'Answers' plus the resource 'snapshots' makes the scope unmistakable.

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

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

The description provides strong contextual usage guidance by explaining why edge age matters ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions the 'competition clock' for interpreting lifespans. It also notes when data gaps occur. However, it does not explicitly name alternative tools or provide 'use this instead of X' exclusions, so it slightly misses the highest bar.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations, explaining the tool's actual computation: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and in basket mode, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It also clarifies that size_usd is max spend on buys and target proceeds on sells. No contradiction with annotations; substantial behavioral context added.

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 structured and information-dense, with separate paragraphs for single-market and basket modes, followed by usage context. It is front-loaded with the core purpose. While it could be trimmed slightly, every sentence adds value given the tool's complexity and the need to explain two distinct modes and risk implications. Earns a high score for organization and efficiency relative to its complexity.

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

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

Given the tool has no output schema, the description compensates by fully enumerating all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers parameter semantics, defaults, constraints, and provides risk warnings. For a complex tool with two modes, this is complete enough to invoke correctly.

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

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

Even though schema description coverage is 100%, the description adds significant meaning: it clarifies that exactly one of `market` or `event` is required, explains the default side behavior in both modes, and distinguishes size_usd interpretation between single-market (max spend/target proceeds) and basket (settlement notional shares per leg). It also notes the default and clamp range for size_usd. This enriches the schema descriptions meaningfully.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by explaining it should be used before acting on their signals. The verb 'check' and resource 'fill risk' are specific and unambiguous.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why this is necessary (theoretical overround on thin books is not capturable, partial fills convert arb into unhedged positions), and clarifies when to use single-market vs basket mode. This is strong when-to-use guidance with a clear alternative context.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses significant behavioral details: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the reality that most pre-mapped topics return warnings. This exposes limitations and edge cases 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 thorough but dense, packing many details into a long paragraph. The front-loaded purpose is good, but the safety-fields section is verbose and could be more scannable with bullet points. Every sentence carries value, but the structure could be improved for readability.

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

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

Given the tool's complexity and lack of an output schema, the description does an excellent job explaining the response structure (prices, top_spreads_pp, safety fields) and edge cases. Minor gaps exist around partial overrides (e.g., providing only one explicit parameter), but overall it is sufficiently complete.

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

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

Though the schema already describes all parameters (100% coverage), the description enhances understanding by explaining the two-mode model: topic mode with pre-mapped shortcuts and explicit mode with ticker/slug overrides. It clarifies the relationship between parameters and output, which the raw schema does not convey.

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 a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from single-venue siblings by emphasizing cross-venue comparison. It further details two modes and the response contents, leaving no ambiguity about what the tool does.

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

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

The description explains both usage modes (topic shortcuts vs explicit ticker/slug) and when the spread is meaningful ('when the bet shapes are equivalent'). It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' providing practical guidance. However, it does not explicitly name alternative tools or when to use them instead.

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 safety is covered. The description adds valuable context about scoping to an identifier ('anonymous IP, BYO key hash, or account ID') and the optional key-listing behavior, 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?

Two sentences with front-loaded core behavior, followed by concise use-case, scoping, and sibling pairing. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationship to siblings. It does not describe return format or error behavior, but given the low complexity and schema examples, the description is sufficiently complete.

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

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

Schema coverage is 100% and the schema's parameter description already states 'omit to list all keys'. The description reinforces this but adds little new syntactic detail. Examples of stored values (ticker, address, research notes) provide semantic context but do not elevate parameter understanding beyond 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?

Description states a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and clearly distinguishes from sibling tools by also covering the list-keys behavior. The contrast with 'remember' and 'forget' makes its purpose unmistakable.

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

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

The description gives clear usage context with examples ('the user's target ticker, an address, prior research notes') and explicitly says to use it to avoid re-deriving context. It mentions related tools ('Pair with remember to save, forget to delete') but does not explicitly state when not to use it or name alternative tools beyond these siblings.

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

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

The description discloses a state-changing side effect (mark_read:true flags events as read, affecting subsequent calls) while annotations claim readOnlyHint:true and idempotentHint:true. This directly contradicts the annotations, misleading agents about the tool's side effects and idempotency.

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, with each sentence serving a distinct purpose: purpose, return payload, filtering/mark_read, and polling/alternative access. No fluff or redundant information; it is front-loaded with the core action.

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 covers return fields, filtering options, the mark_read side effect, and an alternative HTTP endpoint. For a read-oriented polling tool with five optional parameters, this level of detail is sufficient for an agent to use it correctly.

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

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

The schema already describes all five parameters with 100% coverage, so baseline is 3. The description adds value by providing a concrete type example ('sec_8k') and explaining the behavioral impact of mark_read (next call only shows newer events), which 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 clearly states the tool 'Pull fired events from your subscription feed', making the verb and resource explicit. It also distinguishes this from sibling tools by focusing on alerts from the subscription feed, and specifies return fields, filtering, and mark_read 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?

The description gives clear context for retrieving recent alerts and mentions polling works fine. It also provides an alternative access method via the HTTP endpoint for scripts/dashboards, but does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Beyond the readOnly/idempotent annotations, the description discloses fallback behavior (GDELT preferred, GNews on rate-limit/5xx), the USPTO soft-fail due to PatentsView API sunset, that it fans out to multiple sources in a single parallel call, and the exact return structure (changes[] grouped by source, total_changes, pipeworx citation URIs). This is far richer than the annotations alone.

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

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

The description is long but every sentence earns its place by adding distinct details about sources, fallbacks, or parameters. It opens with the user-facing query examples to immediately clarify the tool's purpose, making it front-loaded. The density is justified by the tool's complexity, though it could be slightly 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 explicitly defines the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also explains the API dependencies and failure modes, making the tool's behavior highly predictable. For a multi-source data feed tool, this is fully 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 schema already documents all parameters at 100% coverage. The description adds practical nuances: 'since' examples including relative shorthand ('7d', '30d'), 'value' examples (ticker or zero-padded CIK), and a default recommendation ('30d' or '1m' for monitoring). This supplements 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 clearly identifies the tool as a change feed for a company in a specified time window, with examples like 'what's new with X' and 'updates on Acme'. It enumerates the exact sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from entity_profile by contrasting windowed changes vs static 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?

The description gives explicit when-to-use signals via the example query phrasing and states a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also provides guidance on selecting the 'since' parameter ('Use "30d" or "1m" for typical monitoring'), reinforcing appropriate usage.

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 (which declare it is not read-only and not destructive), the description adds valuable behavior context: storage as a key-value pair scoped by the agent identifier, persistence differences for authenticated vs. anonymous sessions (persistent vs. 24-hour retention). It does not mention what happens to an existing key on re-save, but the idempotentHint annotation partially mitigates that gap.

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

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

The description is concise (four sentences) and front-loaded: the first sentence states the core purpose, followed by usage context, storage details, and companion tools. Every sentence contributes meaningful information with no redundancy or filler.

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

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

For a simple tool with two parameters and no output schema, the description covers all the essential aspects: what it does, when to use it, how data is stored, persistence behavior, and how it relates to recall and forget. There is no missing information that would prevent an agent from using the tool effectively.

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 of both parameters (key and value) with descriptive text. The description's examples and explanation of key-value storage reinforce the schema but do not add substantial new meaning beyond what the schema already conveys, keeping this at the baseline for high schema coverage.

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

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

The description clearly states the tool's function: "Save data the agent will need to reuse later." It distinguishes itself from the closely related siblings recall and forget by explicitly naming them as complementary tools for retrieval and deletion, making its unique role unmistakable.

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

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

The description provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference, research subject) and explains the value proposition (so you don't have to look it up again). It also names the alternatives ("Pair with recall to retrieve later, forget to delete"), fulfilling both the 'when' and 'alternatives' 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by disclosing the exact return fields (ticker, CIK, company_name, RxCUI, ingredient, brand), citation URI formats, and the internal cascade through multiple lookups. This gives the agent a clear model of what the tool will do and produce.

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

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

The description is relatively long but every sentence carries useful information: examples, use cases, return types, and citation details. It is well-structured with clear sections and front-loaded with the most important 'use first' guidance, though a few details could be trimmed for brevity.

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

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

Given that there is no output schema, the description compensates by listing the exact return structure for both company and drug lookups, including citation URIs. It also covers input variants, disambiguation, and the benefit of replacing multiple manual lookups, making it sufficiently complete for an agent to select and use the tool correctly.

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

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

The input schema already documents both parameters with descriptions and an enum for type, so schema coverage is 100%. The description adds extra semantic value by providing real-world examples (AAPL, 0000320193, ozempic, metformin) and explaining behavior like auto-disambiguation, which enriches the schema's raw definitions.

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

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

The description opens with concrete usage examples ('What's the ticker for…') then clearly states the tool's function: resolving a user-spoken name to the canonical identifier required by other tools. This specific verb+resource pair ('resolve entity names to identifiers') and the explicit mention of supported types (company/drug) make the purpose unmistakable, distinguishing it from data-retrieval tools 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?

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also clarifies the supported input formats and entity types, providing clear context for when to invoke it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

Beyond the readOnlyHint, idempotentHint, and openWorldHint annotations, the description discloses the probing mechanism (using ai_visibility_check per entity), the ranking behavior, and the return structure (ranked list with score, confidence, signal density). This adds meaningful behavioral context without contradicting annotations.

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

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

Three concise sentences: purpose, method, use case, and return value. Every sentence adds distinct value and the description is front-loaded with the core function. No fluff or redundancy.

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

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

Despite having no output schema, the description clearly states what the tool returns (ranked list with score, confidence, signal density per entity). The complexity of 4 parameters is well-addressed with usage context, and the tool's relationship to sibling ai_visibility_check is clarified.

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

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

Schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds only marginal framing ('your brand + N competitors') which reinforces the schema's 'first entry treated as subject' but doesn't introduce new parameter meaning.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side with the specific verb 'Compare' and resource 'AI visibility'. It distinguishes itself from sibling tool ai_visibility_check by explicitly mentioning it probes each entity with that tool, making this the multi-entity comparison variant.

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

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

The description provides clear usage context: competitive AI-marketing audits, with an example of comparing brand recognition against competitors. It implies this is for side-by-side comparison rather than single-entity checks, but doesn't explicitly name alternative tools or exclusion criteria.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important operational behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. It also lists the output summary block fields, giving the agent a clear picture of what to expect. This is rich behavioral context that goes beyond the structured metadata.

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 about 120 words and heavily packed with useful information, but it's not overly verbose. It is front-loaded with the core purpose, then flows into usage guidance, output shape, exclusions, and failure behavior. A slight deduction because the list of return fields is long and could be summarized, but overall 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 composite tool with no output schema, the description thoroughly covers the return value (summary block fields, per-advisory detail, links, recent alternatives), ecosystem scope, and timing/failure behavior. It leaves no critical gaps for an agent to know what the tool does and how to interpret its results. This is complete in context.

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

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

Schema coverage is 100%, so the baseline is 3. The description doesn't add much parameter-specific meaning beyond the schema's own descriptions; it restates that 'package' is an npm package name and mentions scoped packages are allowed (already in schema). The 'version' default behavior is also in the schema. Therefore the description adds value in context (e.g., 'NPM ecosystem only') rather than in parameter semantics, so a 3 is appropriate.

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

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

The description opens with a specific and informative definition: 'Composite "should I add this npm package to my project" check in ONE call' and details the two data sources (deps.dev and bundlephobia) and the exact facets evaluated (license, advisories, bundle size, etc.). This clearly identifies the tool's function and distinguishes it from sibling tools like bet_research or deep_research, which have different domains.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly' — a helpful pointer to alternatives without naming a sibling. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: BGE-base-en embeddings with cosine over 500-char overlapping windows, a 200K character cap with truncation flagging, and the exact return format (top-N passages with character offsets and similarity scores). 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?

Four dense sentences, each earning its place: function, use case, pairing with a sibling tool, and implementation details. It front-loads the core purpose and avoids repeating schema field descriptions, making it efficient and scannable.

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

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

Even without an output schema, the description specifies return contents (passages, offsets, similarity scores) and constraints (200K cap, truncation flag). This is complete enough for an agent to select the tool correctly and anticipate 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% with each parameter well-described, and the description adds concrete example texts ('SEC 10-K body, an article, a long tool result') and query examples, plus the truncation behavior beyond the schema's static limits. This enriches the agent's understanding of how to populate the parameters.

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

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

The description opens with 'Semantic search INSIDE a fetched record' – a specific verb, resource, and scope. It distinguishes from siblings by emphasizing it operates on already-fetched text and returns passages with offsets and similarity scores, which is distinct from whole-document tools like ask_pipeworx_grounded.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This names an alternative tool and gives clear integration guidance, satisfying the when/alternative requirement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds behavioral context beyond annotations by listing exactly what is returned (status indicator, vendor status line, degraded components, open incidents, scheduled maintenance) and by noting the ability to query arbitrary hosts via status_host.

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 question and uses a compact structure. It includes a substantial vendor list, which is helpful but slightly lengthens the text. All sentences contribute to understanding the tool's scope, output, and usage, earning a 4 rather than 5 due to the extended list.

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

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

Given the tool has no output schema and only 3 optional parameters, the description carries the burden of explaining return values. It thoroughly describes the output (status indicator, status line, degraded components, incidents, maintenance) and covers the main usage scenarios. It also points to statuspage_list_vendors for the full vendor set, making the context complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a note about status_host ('Pass status_host to check any other vendor running a Statuspage'), but the schema already states 'Use for any vendor outside the curated map.' No additional meaning is provided for vendor or include_components beyond the schema.

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

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

The description opens with a concrete question, 'Is a service down right now?', and states it performs a 'Live service status, outage and uptime check' for 123 Statuspage vendors. It clearly distinguishes itself from siblings by focusing on a general status check for any Statuspage vendor, while listing return specifics like status indicator, incidents, and maintenance.

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

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

The description provides explicit usage intent: 'Use for questions about downtime, outages, service health, incidents in progress and whether an API or platform is working.' It also instructs to 'Pass status_host to check any other vendor running a Statuspage.' However, it does not mention when to prefer sibling tools like statuspage_incidents or statuspage_multi_check.

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 this is read-only, idempotent, and non-destructive. The description adds substantial behavioral context: exact returned fields (lifecycle statuses, impact levels, timestamps, duration, affected components, latest update), the unresolved_only filter behavior, and the status_host override for vendors outside the curated map. There is 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 purpose and organized clearly. It is a bit dense due to the detailed return-field enumeration, but that length is justified because no output schema is provided. Every sentence contributes meaning, with minimal 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?

Given the absence of an output schema, the description does an excellent job of explaining return values, vendor scope, use cases, and the unresolved_only/status_host options. It is effectively self-sufficient for an agent to understand what the tool does, what it returns, and when 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?

The schema already documents all five parameters with solid descriptions, so the baseline is 3. The description adds extra context by framing unresolved_only as a filter for still-open incidents and clarifying that status_host is for vendors outside the curated list, which helps real-world usage.

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

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

The description opens with a specific verb-plus-resource framing: 'Incident and outage history for a vendor's status page — what broke, when, and whether it is fixed.' It clearly focuses on incident/outage history, which differentiates it from sibling tools like statuspage_check or statuspage_multi_check, and details what each incident returns.

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

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

The description explicitly states when to use the tool: 'Use for outage history, past downtime, current incidents and postmortem timelines.' It also gives parameter-level guidance for unresolved_only and status_host, but it does not name sibling alternatives or provide explicit when-not-to-use conditions.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds valuable behavioral context: it returns a total count plus per-vendor fields, and distinguishes between native Statuspage hosts and 'well-known companies whose status pages use a different format' with a URL for humans. This goes beyond the annotation hints without contradicting them.

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

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

The description is three sentences, each earning its place. It front-loads the purpose, then explains return values and the include_elsewhere behavior, and ends with filter options. There is no redundant phrasing or filler; it is efficient yet comprehensive.

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

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

Despite no output schema, the description fully explains what is returned (total count, lookup key, display name, category, status hostname) and the two classes of vendors. With three optional parameters fully described in the schema and clear filtering guidance, the context is complete for an agent to decide when to call and what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds functional meaning by mentioning 'Filter by category or search text' which maps directly to category and query parameters, and it explains include_elsewhere by describing the alternate-format vendors. This reinforces the schema but doesn't restate exact definitions, adding value beyond the property 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 lists verified Statuspage vendors and returns their lookup keys, names, categories, and hostnames. It explicitly distinguishes from statuspage_check by positioning this as the tool to confirm a vendor name before checking status. The verb+resource+scope is specific and unambiguous.

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

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

The description explicitly says 'so a vendor name can be confirmed before calling statuspage_check instead of guessed', providing a clear when-to-use and directing to the sibling tool. It also explains the include_elsewhere option for known vendors using a different format, giving context for that alternative. This is explicit usage guidance.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description goes beyond by detailing the per-row return fields (status indicator, status line, incident count, degraded component count), the roll-up categorization, and handling of unreachable vendors. This adds meaningful behavioral context that the annotations don't 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?

Two sentences, each earning its place. The first sentence states the action and output; the second lists practical use cases. No filler or redundancy. The description is front-loaded with the core purpose, making it scannable.

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

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

Since there is no output schema, the description compensates well by specifying the exact row fields and roll-up behavior. It also addresses the failure case ('could not be reached') and covers realistic usage scenarios. A minor gap is not specifying the range of status indicators, but the roll-up naming implies them.

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

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

The input schema already describes the single parameter thoroughly: vendor names/keys or hostnames with dot detection and a 1-20 entry limit. The tool description merely restates that it takes a list of vendor names or hostnames, adding no new semantic detail. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Check the live service status of several vendors at once.' It immediately distinguishes itself from single-vendor siblings like statuspage_check by emphasizing multi-vendor capability, and the phrase 'are any of my providers down right now?' makes the purpose instantly relatable.

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 enumerates explicit use cases: 'dependency health sweeps, incident triage across a stack, and monitoring a set of upstream APIs in one call.' It does not name alternatives or state when not to use it, but the multi-vendor framing clearly implies that for a single vendor you'd use the single-check sibling. This is clear context without 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?

Adds substantial behavioral details beyond annotations: requires a Pipeworx OAuth account, feed is always on, SMS requires verified phone and has a 10/day cap, webhook returns a signing secret once and auto-disables after 10 failures. No contradiction with the readOnly/idempotent hints.

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

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

The description is dense and front-loaded, with the first sentence stating the core purpose and return value. Every sentence adds useful context about types, requirements, or delivery channels, and the length is justified by the tool's complexity.

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

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

Covers the return value (subscription id), authentication requirement, all supported types, delivery channels, and operational caveats. Although webhook is not explicitly mentioned in the top-level description, it is thoroughly documented in the input schema, so the overall context is complete.

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

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

The input schema already has 100% description coverage with detailed examples. The description adds interpretive value (e.g., items:['5.02'] = officer change, topic:'fed' example) and reinforces key constraints, but does not dramatically surpass the schema's own explanations.

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?

Clearly states it creates a proactive monitoring subscription and returns the new subscription id. This specific verb+resource distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides clear context for when to use the tool (proactive monitoring), enumerates supported subscription types, and mentions recent_alerts as an alternative for pulling the feed. However, it does not explicitly contrast with list_subscriptions or unsubscribe, nor state when not to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds that it returns example questions from a live catalog of thousands of tools and that results include the exact tool + argument shape. This context is useful and not implied by the annotations alone.

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

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

The description is a single dense paragraph but front-loads example queries and then explains purpose, output, parameters, and usage. Every sentence adds value, though it could be formatted with headings or bullets for easier scanning.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what it returns, how to call it, and when to use it. It mentions the key deliverable (exact tool + argument shapes) and provides enough context for an agent to decide whether 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?

The schema already fully documents the optional topic parameter, including the allowed values and the behavior when omitted. The description repeats this information without adding new semantic detail, so it neither enhances nor degrades the schema's clarity.

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 as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on suggesting questions rather than answering them or listing 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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear usage context. It also explains the optional topic parameter to focus results. It does not explicitly state when not to use it, but the guidance is strong.

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 that already indicate readOnlyHint=false and destructiveHint=false, the description adds ownership enforcement and the deactivation-over-deletion mechanism, explaining that historical events remain available. This provides meaningful behavioral context.

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

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

Two sentences, action-first, with no redundant words. Every phrase adds value — the action, the ownership constraint, and the deactivation behavior are all clearly conveyed.

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

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

For a tool with one parameter, rich annotations, and no output schema, the description fully covers the action, constraints, and side-effects. The link to recent_alerts provides sufficient context for expected behavior.

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 the parameter documentation with 'Subscription id (uuid) returned by subscribe.' The description briefly mentions 'by id' but does not add additional meaning beyond the schema.

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

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

The description states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides the ownership constraint ('you can only cancel your own subscriptions') and explains the deactivation behavior with a link to recent_alerts. It does not explicitly list alternatives or when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail: the dual-path routing (SEC EDGAR + XBRL vs. grounded pipeline), return payload (verdict, actual value, citation, reasoning), and tolerance override behavior. No contradictions.

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

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

The description is relatively dense but front-loaded with trigger phrases and includes a benefit statement ('Replaces 4–6 sequential calls'). Each sentence serves a purpose, though it could be trimmed slightly.

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

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

No output schema, so the description compensates by specifying the return structure (verdict types, actual value with citation, reasoning). It covers the tool's complexity: routing, tolerance, and return semantics. Sufficient 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 covers 100% of parameters with descriptions. The description adds semantic value by explaining tolerance_pct's role in overriding the claim-implied tolerance and suggesting values (1–2) for hallucination detection, as well as providing concrete claim examples. This goes 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 natural-language trigger phrases ('Is it true that…', 'fact check', etc.), clearly stating the tool verifies factual claims against authoritative sources. It also distinguishes the two processing paths (SEC EDGAR for company-financial claims, grounded pipeline for others), differentiating it from sibling research tools.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear trigger condition. It also describes the routing logic for different claim types, but doesn't name alternative tools or provide when-not guidance, 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.