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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it routes across a huge internal tool inventory, fills arguments automatically, returns stable citation URIs, and performs well for breaking-news queries. It doesn't mention failure modes or rate limits, but the safety profile is already covered by annotations.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and organized into purpose, examples, and escalation paths. A few phrases are slightly redundant, such as 'even if web search could also answer it', but overall every section 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 high-complexity routing tool with no output schema, the description is unusually complete: it tells the agent what input to send, what kind of answers to expect, when to choose this tool over siblings, and how to handle breaking-news cases. An agent has enough information to invoke it correctly without further inference.

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 gives example questions and clarifies that input is natural language, but it doesn't add meaning beyond the rich schema, 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 states a specific verb-resource pair: it routes a natural-language question to one of 5,706 tools across 1,493 verified sources and returns a structured answer with pipeworx:// citation URIs. It also clearly distinguishes itself from siblings such as ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this over web search, provides a long list of eligible question types and concrete examples, and says 'START HERE for most questions'. It also explains exactly when to step up to ask_pipeworx_grounded or deep_research, giving explicit selection 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?

Discloses the current active status ('No candidate is active right now'), that it matches ask_pipeworx exactly at present, and that candidate routing improvements may be live when under test. This adds meaningful context beyond annotations that already mark the call as read-only and idempotent.

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

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

Four sentences pack in the version, tool scope, live testing status, usage instruction, and caveat. There is slight redundancy between 'identical universal router' and 'matches ask_pipeworx exactly', but no sentence is wasted and key information is front-loaded.

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

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

For a single-required-parameter router with rich annotations and no output schema, the description tells the agent what the tool can do, when to use it, and how behavior may vary. Referencing the same response shape as ask_pipeworx covers return expectations adequately.

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

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

Schema description coverage is 100%: all six parameters are documented, and q, text, input, query, and prompt are each described as aliases for question. The description only repeats 'same arguments' and adds no additional parameter-specific semantics, so the baseline of 3 for high schema coverage is appropriate.

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

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

Description opens with 'Beta version of ask_pipeworx: identical universal router' and names the same 5,706 tools, arguments, and response shape. It clearly differentiates itself from the stable sibling ask_pipeworx and conveys its role as an experimental router.

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

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

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. It also warns 'Falls back to nothing' to prevent the false expectation of a fallback path.

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 read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: grounded extraction, verbatim evidence, explicit refusal reasons, and the exact refusal_reason enum. There is no contradiction with the annotations.

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

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

The description is dense but every sentence earns its place: purpose, behavior, return shape, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the primary purpose and packs the necessary detail without filler.

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

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

For a complex tool with no output schema, the description fully specifies the behavior, output contract, refusal conditions, and relationship to the sibling tool ask_pipeworx. An agent has everything needed to decide when to call it 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 description coverage is 100%, including all aliases, so the schema already documents the single meaningful parameter. The description mentions natural-language questions but adds no parameter semantics beyond the schema, so the high-coverage 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 states a specific, distinctive purpose: a 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results and can return an explicit refusal. It explicitly contrasts with ask_pipeworx, making the differentiation clear without needing to inspect schemas.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists examples like financial verdicts, legal claims, and medical lookups. It also tells the agent when to prefer the alternative: 'prefer ask_pipeworx for casual lookups', and discloses the cost trade-off of one extra LLM call.

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 declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context beyond them: account requirements, parallel decomposition, findings packet structure, explicit gaps[] for unanswered facets, never-inventing findings, fetchable citation_uri, semantic excerpting, and expected latency. No contradiction with annotations.

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

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

The description is long and dense but every sentence earns its place, covering auth, usage context, behavior, limitations, and latency. It is front-loaded with the critical account requirement, though the wall-of-text format could benefit from light structuring; minor penalty 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?

Despite having no output schema, the description fully explains what the tool returns: findings packet with verbatim evidence, confidence, source, fetched_at, hop field, citation_uri, gaps[], and contradictions[]. It also covers auth prerequisites, latency, and second-hop behavior, making it complete for correct invocation and expectation-setting.

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, but the description adds real value beyond the schema: it explains that depth:'standard' performs gap recovery, depth:'thorough' is paid and chases additional leads, and question accepts broad/multi-part natural language because decomposition is the point. This enriches both parameters without repeating the schema verbatim.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources' in one call. It clearly differentiates from siblings by saying 'this is NOT open-web search' and explicitly naming ask_pipeworx as the alternative for single lookups and current news.

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 scoped: best for broad/multi-part questions over structured data, while single lookups and breaking current-news topics should use ask_pipeworx. It even routes around auth requirements by instructing unsigned-in users to use ask_pipeworx instead, leaving no ambiguity about when this tool should be chosen.

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?

Despite the annotations being all false (no hints), the description richly discloses behavior: the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'), rate limits ('Rate-limited to 5 per identifier per day'), and operational details ('The team reads digests daily and signal directly affects roadmap'). It also explicitly states 'Free; doesn't count against your tool-call quota,' which is useful context for an agent deciding whether to invoke.

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

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

The description is long but every sentence earns its place. It packs purpose, exclusions, workflow, rate limits, and quota into a well-structured paragraph. There is no redundant or vague phrasing; each clause introduces new, actionable information for the agent.

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

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

For a tool with no output schema and four parameters including a nested object, the description is remarkably complete. It covers all modes (bug, feature, data_gap, praise), what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), how to retrieve results, and constraints. The agent can use this tool correctly without needing additional 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?

The schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds meaningful usage semantics beyond the schema, particularly for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed' and instructs to pass it 'with no other arguments.' This contextual clarification enhances the agent's understanding of how parameters interact, justifying a score above baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from other MCP server feedback channels by stating 'ONLY for tools served by this Pipeworx connection' and contrasting with 'another vendor's Gmail, Splunk, Slack, etc. connector.' This makes the tool's 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 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 a clear exclusion: 'if the tool came from a different MCP server... we cannot fix it and reporting it here only delays you; file it with that server instead.' This is exactly the kind of decision support an agent needs.

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

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

Annotations already indicate 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?

Annotations already indicate read-only, open-world, idempotent behavior, and the description adds extensive non-obvious behavior: compatibility_warning and compatibility_codes[] can be non-empty even with matched pairs, unknown legs are never paired, skipped_cross_type/subtype counters show dropped comparisons, and temporal_alignment indicates whether resolution periods match. It also warns that pre-mapped keys have an always-set unverified flag. This goes far beyond what annotations alone provide.

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

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

The description is long but dense and organized with clear labels: mode selection, response shape, safety fields, codes, and a final caveat. It front-loads the core purpose and keeps the most operationally critical warnings near the end. A few details are redundant with the schema, but overall every section earns its place given 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?

There is no output schema, so the description correctly takes on the burden of explaining return values: per-venue leg prices, matched_spreads, top_spreads_pp, compatibility fields, skipped categories, temporal alignment, and per-entry flags. It also covers the real-world caveat that most pre-mapped topics are not tradeable signals. Nothing essential for invoking or interpreting the tool is missing.

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

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

The input schema already documents all three parameters with 100% coverage, including the exact topic list, example ticker/slug formats, and override behavior. The description reinforces how the modes interact with the parameters, but it does not add much parameter-specific 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 opens with a precise statement of the tool's job: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes this from sibling tools by naming both venues and focusing on same-question cross-venue comparison, and the two-mode explanation makes the operation concrete.

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

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

The description gives clear context for when to call it — comparing prices for the same question across the two venues — and explains the two modes (topic shortcuts vs explicit ticker/slug pairing). It also warns that pre-mapped topics are often not tradeable and that compatibility fields must be checked. It does not explicitly name alternatives like polymarket_arbitrage, so it just misses the top score.

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?

Description discloses behavior beyond annotations: it returns identifiers labelled with source, states unresolved identifiers explicitly, explains cascading internal lookups, and mentions graceful degradation if GLEIF/OpenFIGI are unavailable. This adds rich context (ownership data, ISIN-to-LEI mapping) that annotations like readOnlyHint and idempotentHint do not convey.

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

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

The description is long but efficient. It front-loads with user-phrase examples that help an agent recognize triggering intents, then covers supported types, identifiers, sources, and fallback behavior. Every clause adds operational detail; while a few phrases could be tightened, the density is justified given the tool's complexity.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It explains return contents (identifiers with source labels), the unresolved field, degradation behavior, input coverage (non-US issuers), and internal cascading. No major gaps are apparent for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains how each enum value behaves, describes acceptable input formats per type, and clarifies edge cases like ISIN resolving to the legal entity and drug returning RxCUI plus citation. This goes far beyond the schema's brief descriptions, making parameter semantics significantly richer.

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

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

Purpose is clearly stated: resolve a user-spoken NAME to canonical/official identifiers required by other tools. It names the exact verbs and resources (ticker, CIK, LEI, RxCUI) and distinguishes from siblings by its role as the ID resolver, even explicitly contrasting with the 2-3 manual lookups it replaces.

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 FIRST whenever you have a name but need an ID." It also clarifies supported types and input forms. It does not explicitly list when-not-to-use or alternative tools, but the strong 'use FIRST' directive and clear scope make the intended usage unambiguous.

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

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

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context by enumerating exactly what the tool returns (status indicator, status line, degraded components, open incidents, maintenance) and notes that maintenance is shown 'where the page publishes it', implying variability. No contradiction with annotations.

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

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

The description is long but information-dense, front-loaded with a question and followed by a structured list of outputs and use cases. The lengthy vendor enumeration is somewhat redundant given a sibling tool (statuspage_list_vendors) exists, but it serves as useful examples. Overall, every sentence contributes to understanding the tool's purpose and behavior.

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

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

Given the absence of an output schema, the description effectively communicates the return contents (status, components, incidents, maintenance) and usage. It also clarifies the status_host parameter for arbitrary vendors. It doesn't describe the exact response format or potential limitations (e.g., rate limits), but for a simple status-check tool with strong annotations, 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?

Input schema coverage is 100% with detailed descriptions for all three parameters. The description reinforces the status_host usage ('Pass status_host to check any other vendor running a Statuspage') but this largely mirrors the schema's explanation. Since the schema already carries the semantic load, the description adds minimal extra meaning beyond what's provided.

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

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

The description opens with a clear question ('Is a service down right now?') and specifies the tool's function: checking live service status for 190 Statuspage vendors. It lists concrete return elements (status indicator, status line, degraded components, incidents, maintenance) and adds a status_host option for any other vendor, making 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 explicitly states when to use it ('Use for questions about downtime, outages, service health, incidents in progress and whether an API or platform is working'). However, it does not mention alternatives such as statuspage_incidents for incident-only queries or statuspage_multi_check for multiple vendors, so it lacks exclusions and alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description is consistent. It adds valuable behavioral context: curated vendor coverage, per-incident fields returned, unresolved_only filtering, and status_host override semantics. 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 one dense paragraph but front-loads the primary purpose and packs in return-field details, filtering options, and the curated vendor scope without redundant filler. Slightly long but 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?

With no output schema, the description adequately explains return values (title, lifecycle status, impact level, timestamps, duration, affected components, latest update) and parameter behavior. It covers the tool's scope and edge cases like status_host sufficiently for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the description doesn't need to explain every parameter. It adds context for status_host ('vendors outside the curated map') and unresolved_only, but mostly reinforces the schema's own descriptions. This meets the baseline of 3.

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

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

Description clearly identifies the resource as 'Incident and outage history for a vendor's status page' and elaborates what is returned. It distinguishes itself from sibling tools like statuspage_check or statuspage_multi_check by focusing on historical incidents and outage timelines.

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

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

Explicitly says 'Use for outage history, past downtime, current incidents and postmortem timelines' and instructs when to use status_host for vendors outside the curated map. It doesn't name sibling alternatives or state when not to use the tool, but provides 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: it returns a total count, per-vendor details, and additionally lists vendors with a different status format when requested. No contradiction.

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

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

The description is four sentences, each contributing unique information: scope, return value/use case, elsewere list, and filtering. It is a bit wordy but not redundant, earning a 4.

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 listing tool with no output schema, the description is comprehensive: it covers what is returned, the purpose, the elsewere behavior, and filtering options. With good annotations and parameter descriptions, nothing essential is missing.

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

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

Schema coverage is 100% and each parameter already has a description. The description only summarises 'Filter by category or search text', which adds minimal extra meaning over the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns a list of supported vendors with their lookup key, display name, category, and status hostname. It explicitly distinguishes itself from the sibling statuspage_check by noting it confirms vendor names before calling that tool, avoiding guessing.

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

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

It explicitly says to use this tool to confirm a vendor name before calling statuspage_check, and mentions filtering by category or search text. This gives clear when-to-use guidance and references 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?

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?

The description goes far beyond the annotations by explaining the verdict types, the meaning of 'could_not_verify' vs 'unsupported', the presence of verification_error with stage/detail, and that 'could_not_verify' must not be shown as evidence. It also details the dual pipeline behavior and citation format, providing rich behavioral transparency.

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

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

The description is long but densely packed with essential information: examples, routing, verdicts, error semantics, and efficiency gains. Every sentence contributes value, though the opening list of example phrasings is somewhat redundant and could be shortened without loss of meaning.

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

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

The tool has no output schema, so the description fully compensates by explaining all return values (verdicts, actual value, citation, reasoning) and error conditions. It also covers both financial and non-financial paths, making it complete for an agent to understand the tool's behavior and expectations.

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

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

Input schema covers 100% of parameters with detailed descriptions, especially tolerance_pct which already explains override semantics, range, defaults, and hallucination-detection usage. The description itself adds no new parameter-level detail beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with specific verb+resource and scope. It provides concrete example queries and explains the two processing paths (SEC EDGAR for financial claims, grounded pipeline for others), making its purpose unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing logic and notes that it replaces 4–6 sequential calls, giving clear context on when to invoke it. However, it does not name alternative sibling tools or provide explicit 'when not to use' guidance.

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