dadjokes

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable behavioral context beyond that: the default free model, that `_apiKey` is passed straight through to Anthropic, and that the user pays Anthropic directly. It does not discuss rate limits or failure modes, but the annotations cover the core safety profile.

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

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

The description is three sentences, front-loaded with the primary action, then adds cost/usage details, and concludes with use cases. Every phrase earns its place; no filler or repetition of structured fields.

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

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

With no output schema, the description appropriately summarizes the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the main parameter behaviors, cost implications, and intended use cases, making it complete for a read-only, non-destructive probing tool with moderate complexity.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds meaning by explaining the default model selection, the conditional requirement for `_apiKey` when probing Anthropic, and the significance of the `models` array. This goes beyond a simple restatement of the schema.

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

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

The description opens with a specific verb ('Probe') and a clear resource ('one or more LLMs') plus the core function: scoring visibility (0-100) per model. It distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on LLM knowledge and visibility scoring for business entities.

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

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

It states explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies the default model and optional Anthropic key. However, it does not name alternative tools or provide when-not-to-use guidance, so it falls short of the highest bar for explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond this: it routes to sub-tools, returns stable pipeworx:// citation URIs, works on every tier, and makes one fast call. It does not discuss failure modes or edge cases, but the annotation coverage lowers the burden.

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 front-loads the critical 'PREFER OVER WEB SEARCH' directive, provides concrete examples, and structures alternatives in a logical progression. Despite its length, it remains scannable and efficiently conveys routing behavior, citations, and step-up guidance without redundancy.

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

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

For a tool of this complexity—routing to 5,564 tools—the description is remarkably complete. It covers what it does, when to use it, when not to use it, what outputs to expect (citation URIs), and how it compares to siblings. The input schema is minimal and fully documented; no output schema exists, but the description explains the return format ('structured answer with stable pipeworx:// citation URIs').

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

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

The input schema has 100% description coverage: the only semantic parameter 'question' is described as accepting natural language with five aliases. The description adds examples of valid questions and reinforces natural language usage, but does not add new parameter-level semantics beyond what the schema already documents. 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 that ask_pipeworx routes factual questions to one of 5,564 tools across verified sources and returns structured answers with citation URIs. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and distinguishes itself from siblings by explicitly naming alternatives like 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?

Description opens with 'PREFER OVER WEB SEARCH' and instructs 'START HERE for most questions', giving explicit when-to-use guidance. It provides concrete trigger phrases, examples, and step-up conditions for alternatives, including when to use ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part queries).

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

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

The description adds context beyond annotations by explaining the dynamic experimental nature (candidate routing improvements, current inactivity, comparison against stable router). Annotations already indicate safe/idempotent behavior, and the description complements this with changeable routing behavior, enhancing 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 concise and front-loaded, with each sentence providing necessary context: identity, current state, usage directive, and clarification of its full functionality. It is appropriately detailed without being verbose.

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 broad router tool with 5,564 underlying tools, the description effectively captures its role, relationship to the stable version, and current behavior. It mentions same response shape as ask_pipeworx, which is sufficient given the sibling context, though it doesn't detail output structure.

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

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

Schema covers all 6 parameters with descriptions (aliases for question). The description does not add any semantic detail beyond schema, but since coverage is 100%, the baseline is met without extra compensation needed.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx, a universal router. It states it is identical in functionality but with potential routing improvements when active, and currently matches ask_pipeworx exactly. This provides a specific purpose and differentiates it from the stable sibling tool.

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 like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router. This gives clear when-to-use guidance, though it does not state explicit when-not-to-use scenarios beyond implying stability preference.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds detailed behavioral context: it mentions the internal process (picks tool, fills arguments, fetches data), the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), refusal reasons, and the extra LLM call cost. This goes far beyond the annotations and is consistent with them (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 front-loaded with the core purpose, then provides structured details on behavior, refusal cases, usage guidance, and cost. Every sentence adds valuable information without redundancy. It is a bit long but appropriately so given the complexity, and the organization maximizes 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?

For a tool with no output schema, the description fully specifies the expected return structure and refusal reasons, covers when to use it vs. the sibling ask_pipeworx, and explains the cost tradeoff. It also distinguishes itself from other siblings in the list (e.g., ask_pipeworx_beta) by emphasizing groundedness. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the description does not need to add parameter details. The description mentions 'fills arguments' but that is about internal routing, not about how to supply the input. The schema already documents the question parameter and its aliases comprehensively; the description adds no additional parameter semantics.

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

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

The description states a specific verb+resource: it is a hallucination-resistant answer mode that routes to the right tool and extracts answers only from fetched data. It distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness and from other siblings by focusing on high-stakes reads.

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

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

Explicitly states when to use (answers that will be quoted, cited, or acted on; high-stakes domains like financial or legal) and when not (casual lookups, prefer ask_pipeworx due to extra cost). Names the alternative tool directly, providing clear decision-making 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 declare readOnly/openWorld/idempotent, and the description adds a wealth of behavioral detail beyond that: resolver contract with market_match_confidence and suggestions, low-confidence short-circuit with status, closed/dead market handling, news fallback flags, wide-spread illiquidity notes, and resolution-rule risk parsing. This goes far beyond annotations and gives the agent clear expectations.

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 clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every section adds useful information for a complex tool, but it could be tightened; some details like the de-indexing explanation are slightly redundant with the low-confidence path. Overall it earns its place.

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

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

With no output schema, the description thoroughly explains the response structure (result.market, result.analysis, result.evidence, parent_event, news fields), statuses, and edge cases. It also warns about resolution-rule risk and resolver confidence, making it highly complete for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the market input forms already in the schema and does not add meaningful extra info about depth or include_raw. It provides contextual color about the fan-out behavior but not parameter-level semantics beyond what the schema states.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further details the input forms (slug, URL, question text) and the output (evidence packet + market-vs-model comparison), clearly distinguishing it from sibling tools like polymarket_edges or polymarket_arbitrage.

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 "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides context about blocker statuses and resolution-rule risk checks. However, it does not explicitly name alternative tools or when-not-to-use, so it falls short of a 5.

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

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

Annotations already indicate readOnly and idempotent behavior. The description goes further by detailing exact data sources (SEC 10-K financials, FAERS counts, FDA approvals, trial counts), how off-calendar fiscal years are handled, and that results are sorted by primary metric. This adds substantial transparency beyond the annotations.

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

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

The description is appropriately sized—about five sentences—but each sentence carries essential information: trigger phrases, the core function, data details, sorting behavior, and efficiency benefits. It is front-loaded with purpose and usage, making it highly 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?

For a two-parameter tool without an output schema, the description is remarkably complete. It explains what data is pulled, how results are organized, and that returned data includes citation URIs. Edge cases like off-calendar fiscal years are noted, ensuring the agent has full context to invoke the tool correctly.

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

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

Although schema coverage is 100%, the description enriches both parameters. It explains the semantic difference between type='company' and type='drug', provides concrete examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"], and clarifies that values map to tickers/CIKs or drug names. This goes beyond the schema's basic type definitions.

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

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

The description clearly identifies the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single call. It provides trigger phrases like 'X vs Y' and 'rank these companies,' and distinguishes itself from single-entity lookups by explicitly stating it should be preferred over sequential lookups.

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

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

The description gives explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists concrete query patterns and explains when type='company' vs type='drug' should be used. This clearly informs the agent when to select this tool over alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account requirements, depth tiers, gaps[] never invented, stable citations always fetchable, semantic excerpting, latency expectations, and contradiction scanning. No contradictions with annotations.

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

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

The description is long but information-dense, front-loading the critical account requirement and alternative. Every sentence adds operational or selection value, though it could be more scannable with breaks. 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?

Despite having no output schema, the description fully explains the return content: findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field. It also covers auth, limitations, and performance, making it complete for a complex research 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% and both parameter descriptions are detailed (depth enum behavior, question guidance). The description adds little beyond what the schema already provides; depth tier details and 'broad/multi-part is fine' are also in 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 specifies a clear verb and resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explains it decomposes the question, routes to sub-tools, and returns a findings packet. It explicitly differentiates from siblings like ask_pipeworx by stating this is NOT open-web search and is best for broad/multi-part questions.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states an alternative if not signed in: 'use ask_pipeworx instead'.

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

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

Annotations already convey that the tool is read-only, idempotent, and non-destructive. The description adds valuable behavior context beyond these: it explains the return format (top-N tools with names, descriptions, full input schemas, and curated examples), states that results are 'ready to call directly' with no second schema lookup, and positions the tool as a first-step meta-query. This meaningfully extends the annotation-only picture, though it does not describe edge cases like empty result sets or error 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 front-loaded with the core purpose in the first sentence, then gives a useful domain list, followed by the return-value detail and a clear usage directive. It is a bit longer than necessary due to the domain enumeration, but every part contributes to selection and invocation confidence. No fluff or redundancy. The structure flows logically from what → when → what you get → when to use it.

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

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

This tool has no output schema, so the description carries the full burden of explaining what the agent will receive. It explicitly states that returns include names, descriptions, and full input schemas with examples, and that results are directly callable. It also explains the query parameter semantics and gives clear usage context (call first). Given the tool's role as a discovery tool, this description covers all essential aspects for correct use. There is no missing information that would cause an agent to misuse it.

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

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

All parameters (including aliases) are fully described in the schema, so the baseline is 3. The description reinforces the meaning of 'query' by calling it a 'natural language description' and providing examples ('analyze housing market trends'), but it does not add new parameter-specific semantics beyond what the schema already states. The description's mention of 'top-N' indirectly relates to the 'limit' parameter, but not in a way that clarifies syntax or defaults over the schema. Thus, no extra credit.

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 combination: 'Find tools by describing the data or task.' It clearly names the tool's function as a discovery/search mechanism and even enumerates the domains it covers (SEC filings, FDA drugs, etc.), making it unmistakable what this tool does. It also distinguishes itself from sibling tools by positioning itself as a meta-tool ('Call this FIRST'), so it is not confused with specific research or lookup 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 states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This is strong usage guidance. It does not name specific alternatives (like sibling tools), but the priority instruction and the 'not just one answer' clause implicitly communicate when not to use it (when you need a single answer). Missing explicit 'when-not' examples keeps it from 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 read-only/idempotent, and the description adds detailed behavioral context: it fans out across SEC EDGAR, XBRL, USPTO, news, and GLEIF; lists exact returned fields; notes patent API sunset soft-fail; and explains GDELT→GNews fallback. 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 text is dense with examples and specifics, but each sentence adds value. It front-loads with natural language queries and organizes returned data. Slightly longer than ideal but justified by the need to describe a multi-source tool.

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

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

With no output schema, the description succeeds in conveying what callers receive (CIK, filings URIs, fundamentals sorted by period_end, patent status, news fallback, LEI) and the exact input constraints. It gives enough to invoke and interpret results.

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

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

Schema already covers both params (type, value) 100%, and the description adds example values ('AAPL', '0000320193'), zero-padded CIK requirement, and the restriction that names are unsupported—materially enriching parameter semantics.

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

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

The description opens with multiple user-phrase examples and explicitly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools by instructing to prefer it over chaining single-lookups and by providing a distinct resource (company entity).

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

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

Provides explicit when-to-use guidance ('when the user asks for a holistic view'), states 'ALWAYS PREFER over chaining...' and gives an exclusion case (names not supported, use resolve_entity first). This is strong 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 cover destructive and non-read-only behavior. The description adds context that the memory was 'previously stored' and 'saved earlier,' reinforcing it only affects agent-saved data. This is useful but not substantial beyond annotations.

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

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

The description is two sentences with the main action front-loaded, followed by usage guidelines and related tools. Every sentence earns its place with no redundant information.

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

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

For a simple single-parameter tool, the description covers purpose, usage, and related tools. Annotations handle destructive and idempotent aspects, and no output schema is expected. It could explicitly mention irreversibility, but destructiveHint already signals this.

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

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

The schema has 100% coverage for the 'key' parameter with 'Memory key to delete.' The description's 'by key' merely repeats the schema, adding no new meaning. Baseline 3 is appropriate since schema fully documents the parameter.

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

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

Description clearly states 'Delete a previously stored memory by key,' identifying the specific action and resource. It distinguishes itself from siblings by mentioning pairing with remember and recall, making its role in the memory workflow explicit.

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

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

Provides explicit usage scenarios: when context is stale, task is done, or clearing sensitive data. It names related tools (remember and recall) but does not explicitly state when to use those alternatives instead of forget, so it lacks full when-not guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also describes the output as a single text blob for drop-in placement, which is useful for the agent. The description does not contradict annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then process, then use cases. Every sentence earns its place without wasted words. It is concise and well-structured for quick agent consumption.

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 relatively simple tool with no output schema and only two parameters, the description is complete. It covers the action, the process, the output format, and the intended use cases. Given the richness of the annotations and schema, no critical information 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 has 100% description coverage for both parameters (url and max_links). The description mentions 'any URL' and the output, but does not add meaningful semantic detail beyond the schema. The baseline of 3 applies because the schema already carries the parameter documentation.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the action (generate), the resource (llms.txt file), and the target (any URL). It distinguishes itself from sibling tools by emphasizing the output and indexing use case, making it clear this is about file generation, not analysis or checking.

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.' This gives clear context for when to use the tool. However, it does not mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the core safety profile. The description adds that it 'Returns the full joke text,' which is useful but does not disclose error behavior, rate limits, or other potential edge cases. This is consistent with the reduced burden when annotations are present.

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

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

The description is a single sentence, concise, and front-loaded with the verb and resource. Every word conveys essential information without redundancy, making it highly efficient.

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

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

For a simple lookup tool with one parameter, full schema coverage, and comprehensive annotations (readOnly, idempotent, non-destructive), the description is complete. The existence of an output schema further reduces the need to explain return values. The tool's behavior is fully captured by the current description.

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

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

The input schema provides 100% coverage with a clear description for the single 'id' parameter ('The ID of the dad joke to retrieve'). The tool description does not add additional parameter semantics beyond what the schema already documents, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Retrieve' and clearly identifies the resource as 'a specific dad joke by ID.' It distinguishes itself from siblings like random_joke and search_jokes by focusing on retrieval by ID, making its purpose immediately clear.

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

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

The description implies the appropriate use case: when you have a specific joke ID and want the full joke text. It does not explicitly name alternatives or provide exclusions, but the context ('by ID') gives clear guidance. Without explicit comparison to random_joke or search_jokes, it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context: it scopes to 'caller's' subscriptions and specifies return fields plus the default of active-only. No contradictions, but it doesn't discuss potential edge cases like empty results or pagination; however, the annotations carry the safety burden.

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 with zero fluff. It front-loads the purpose, then lists return fields, then gives usage guidance. Every sentence earns its place and the structure is 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 simple list tool with one optional parameter, the description covers what it does, what it returns, and when to use it. The rich annotations cover side effects, and the description compensates for the lack of an output schema by listing the return fields. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% for the only parameter ('include_inactive' with 'Include cancelled subscriptions in the response (default false)'), so the schema fully explains the parameter. The description adds minimal extra meaning beyond setting context with 'active subscriptions', matching the baseline 3 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 action (List) and resource (the caller's active subscriptions), and lists the returned fields (id, type, params, etc.), making the tool's purpose concrete. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on read-only retrieval.

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 tells when to use it: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly implies the tool is for review and pre-cancel/id lookup, and indirectly contrasts with subscribe/unsubscribe alternatives.

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

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

Annotations are all false and unhelpful (readOnlyHint=false, etc.), so the description must bear the full burden. It does: explains the claim_token mechanism (filing without an account returns a token that can be passed later to read status), discloses rate limiting (5/day), pricing (free, no quota), and team response cadence (daily digests). No contradictions with annotations.

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

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

While longer than some examples, every sentence earns its place. The description is front-loaded with purpose, then logically covers usage cases, exclusions, mechanics, and constraints. No redundancy or fluff; 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?

Despite no output schema, the description explains what to expect from filing (claim_token) and from later token use (status and resolution details). It covers scope, format, rate limits, and cost. For a 4-parameter, non-destructive feedback tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: it demonstrates how to use claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})'), explains what the token does (read whether fixed and what changed), and gives guidance on message specificity. This elevates it 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 from siblings by focusing on feedback about Pipeworx tools, explicitly contrasting with tools from other MCP servers. This is a textbook clear purpose statement.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit when-not-to-use (tools from other servers) with rationale ('we cannot fix it'). It also advises to describe issues in terms of Pipeworx tools and not to paste end-user prompts, offering strong decision support.

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, and non-destructive behavior. The description adds valuable context: caching delay (5min-1h), data provenance (CF analytics-engine), and privacy (no PII, just pack/tool/count). This goes beyond annotations without contradicting them.

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

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

The description is moderately sized but well-structured, starting with a hook, then outputs, use cases, and data characteristics. The numbered use cases make it easy to scan, and no sentences are wasted.

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

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

Despite having no output schema, the description sufficiently covers the return contents (top tools, top packs, call volume), the data source, caching behavior, and use cases. For a simple tool with one optional parameter, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances the 'window' parameter by explaining the trade-off: shorter windows surface current trends, longer show steady-state demand. This adds meaning beyond the enum values.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb ('Returns') and resource ('Pipeworx'). It distinguishes itself from siblings by mentioning 'what other AI agents are calling on Pipeworx right now,' which is unique among the listed 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 three explicit use cases, such as discovering hot data sources and confirming canonical tools, which guide when to use it. However, it does not explicitly mention when not to use it or name alternative tools like discover_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 read-only and non-destructive, but the description adds extensive behavioral detail: detection logic (monotonicity ordering, partition-sum ≈1, >3pp threshold), Jaccard similarity filter, placeholder filtering rule, response structure, and fill check pricing with explicit warning not to trade when realizable edge ≤0. 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 long but well-structured with clear sections for modes, filters, response, and fill check. Every sentence adds value, but it could be tightened without losing information. Overall 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?

Covers all aspects: both modes, default no-args behavior, detection thresholds, filters, response fields (opportunities[], partition_check), fill check semantics, and cross-reference to polymarket_fill_risk. With no output schema, the description effectively documents the return structure.

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 both parameters described, but the description greatly enriches meaning by detailing what each mode does: event walks child markets and checks date/threshold ordering plus partition check; topic searches related events and flattens markets. It also explains no-args behavior, which the schema doesn't cover.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with specific verbs and resource. It distinguishes its two modes (event vs topic) and even references a sibling tool (polymarket_fill_risk) for custom sizing, separating its own scope.

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

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

Provides explicit usage guidance: no args for trending_scan, event for specific markets, topic for cross-event scanning, and recommends event for a specific market. It explains when cross-event mode is advantageous and when not to trade based on fill check, plus names an alternative tool for custom sizing.

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 numerous behavioral traits beyond the annotations: 1-hour KV-level caching keyed on knobs, diagnostics (_diagnostics with funnel counters, filter_skips), the logic behind each model family, the 24h-move warning, and the caveat on Fed signals. These add substantial context beyond readOnly/openWorld/idempotent hints and show 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 long but densely structured, with clear section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, RESPONSE TOP-LEVEL, TRADEABLE-EDGE KNOBS). Every sentence adds technical detail, but the sheer volume could be slightly pruned; still, it is far from wasteful and deserves 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?

Given the tool's complexity, the absence of an output schema, and the rich input schema, the description goes above and beyond to explain the response structure (by_segment, fed_candidates/fed_note, _diagnostics), the logic for edge calculations, slippage handling, caching, and edge-case filters. It provides a complete mental model for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds strategic meaning for key knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), especially the caveat that partition arbs always return kelly_fraction_half=0 and that min_partition_leg_kelly applies per-leg inside top_legs. This goes beyond the schema by explaining interaction effects.

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 ('Scan top Polymarket markets') and resource ('return opportunities where Pipeworx data disagrees with market price'), clearly distinguishing from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It also declares its intended use case ('what should I bet on today'), making purpose unambiguous.

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

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

The description provides clear context on when to use the tool ('Built for what should I bet on today — agents discover opportunities without paging hundreds of markets') and explains design choices (e.g., Fed bets excluded, concentrated_longshot rare-by-design). However, it does not explicitly contrast with sibling tools or state when not to use it, 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?

Beyond the readOnlyHint and idempotentHint annotations, this description discloses extensive behavioral details: response structure (tracked[], expired[], snapshot_dates[]), data gaps due to cache-miss, 60-day TTL limitations, decay computed on |edge_pp_net| with sign explanation, and that values are daily closes not intraday. This goes far beyond basic 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 exceptionally well-structured: it opens with a succinct purpose, then proceeds through args, a detailed RESPONSE breakdown, and LIMITS. Every sentence carries meaningful information, and the bolded section headers (RESPONSE, LIMITS) aid scanning without wasted words.

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

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

With no output schema, the description fully explains the return value semantics, including the meaning of expired opportunities and 'median lifespan is your competition clock.' It covers parameter effects, data gaps, and historical limits, making it comprehensive for a read-only 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 input schema already provides 100% coverage for both parameters (days and window) with clear descriptions. The description's inline args line ('days (lookback, default 14, max 30), window (snapshot family, default '1wk')') mostly restates the schema without adding new semantic depth, so it neither compensates for nor exceeds the schema's baseline.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It defines the exact question it answers ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edges.

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

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

The description provides strong contextual usage guidance via the example of a 'fresh wide edge vs a 3-week-old wide edge,' implying when to use this tool for evaluating edge maturity. However, it does not explicitly name alternatives or state when NOT to use it, leaving a small gap in direct comparison to 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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context: it walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and per-leg details. It also explains the risk of partial basket fills and forced directional risk, which goes far beyond the annotations. No contradiction with annotations; the description enhances understanding of side effects and output semantics.

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 carries critical information for two distinct modes. It is front-loaded with the core purpose and then structured into SINGLE-MARKET and BASKET sections, making navigation easy. It could be slightly more concise, but the density is justified by the tool's complexity.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description fully compensates by enumerating return fields for both modes, explaining edge cases (thin legs, partial fills), and providing risk warnings. It covers parameters, outputs, use cases, and failure modes, making it complete for an agent to select and invoke correctly.

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

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

Although the schema covers all parameters, the description adds crucial semantic layers: it clarifies that market and event are mutually exclusive modes, explains side defaults per mode, and reinterprets size_usd as settlement notional in basket mode. It also lists outputs tied to parameters. This goes beyond the schema's basic descriptions, enriching the meaning of each parameter.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges signals, explaining it is a pre-trade risk check for those tools. This is a precise, non-tautological purpose statement.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why: theoretical overround on thin books is not capturable and partial basket fills convert arb into unhedged directional positions. This is exemplary usage guidance with concrete thresholds and alternatives implied.

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?

While annotations already declare the tool read-only and non-destructive, the description goes far beyond by disclosing specific behavioral traits: the compatibility_warning conditions (a and b), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also warns that pre-mapped topics are not automatically tradeable, providing deep transparency into limitations and edge cases.

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

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

The description is long but dense and well-structured, using labeled sections like 'TWO MODES,' 'RESPONSE,' and 'SAFETY FIELDS.' It is front-loaded with the core purpose, and every sentence adds essential context—no fluff. For a tool with this complexity, the length is fully justified.

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

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

With no output schema, the description must explain return values, and it does: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skip counters. It covers all aspects needed for an agent to invoke the tool and interpret results correctly, even including a caution about the rarity of real spreads.

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 meaning beyond the schema by explaining that explicit tickers 'override' the topic-mapped side, and by listing the topic shortcut values. It also explains that kalshi_event_ticker + polymarket_event_slug are for 'custom pairings,' which is not fully captured in the schema alone.

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

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

The description opens with a clear, specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes the tool from siblings by explicitly naming both venues and the 'spread' concept. It also details two modes (topic shortcuts and explicit pairings), making the purpose unambiguous.

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

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

The description provides clear usage context: explains both modes, shows when the tool will warn about incompatibility, and cautions that 'most pre-mapped topics return compatibility_warning today.' However, it does not explicitly name alternative tools for when not to use this one, so it falls short of a 5 on the rubric's 'alternatives' criterion.

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 profile is covered. The description adds valuable context by naming the external source (icanhazdadjoke.com) and the exact return shape (joke text and ID), which goes beyond annotations.

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

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

The description is two short sentences with no filler. The key verb and resource are front-loaded, and every word adds 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 is simple, has an output schema, and annotations cover safety. The description provides enough behavioral context (source, return values) to be fully understood without any gaps.

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

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

There are zero parameters and the schema coverage is 100%, so the baseline is 4. The description adds no parameter-specific details, but none are needed since the tool takes no input.

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

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

The description starts with the specific verb 'Fetch' and clearly identifies the resource: 'one random dad joke from icanhazdadjoke.com'. It also states the return values ('joke text and alphanumeric ID'), which distinguishes it from sibling tools like get_joke (specific joke) and search_jokes (search).

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

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

The description implies usage context: use this when you need a random dad joke. It does not explicitly name alternatives or exclusions, but the 'random' qualifier clearly separates it from search/get siblings, providing clear context without needing explicit contrast.

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, and non-destructive behavior. The description adds valuable context: the tool is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys, which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence earns its place. It efficiently conveys purpose, usage, scoping, and related tools without redundancy.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers the two modes of operation, scoping, and complementary tools, providing sufficient information 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 baseline is 3. The description adds meaningful context by giving examples of keys (target ticker, address, research notes) and clarifying the dual behavior when the key is omitted, enhancing the schema's description.

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

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

The description clearly states a specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It distinguishes itself from siblings by referencing remember and forget, 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?

The description gives clear context: use it to look up previously stored context without re-deriving it. It also mentions pairing with remember and forget, but does not explicitly state when not to use it or name alternative tools beyond these companions.

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 explicitly discloses a side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the readOnlyHint=true annotation, which implies no state changes. Therefore, per the rubric, transparency scores 1 due to annotation contradiction.

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

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

The description is compact, front-loaded with the primary action, and every sentence adds value. It covers the return payload, filtering, mark_read side effect, and alternative access in five efficient sentences without unnecessary fluff.

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

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

Given the tool's moderate complexity (5 optional parameters, no output schema), the description covers the essential aspects: what is returned (source, citation_uri, event payload), filtering options, the mark_read behavior, and polling suitability. The schema covers parameter details, and annotations cover safety, so 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 description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by giving a concrete example for 'type' ('sec_8k'), specifying 'since' as an ISO timestamp, and explaining the behavior of mark_read. This elevates it to a 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Pull fired events from your subscription feed.' It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on the persisted feed of fired alerts, including field details and filtering.

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 on when to use the tool (polling, filtering by type/since, marking read) and even provides an alternative access method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly contrast with sibling tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive. Description adds fallback behavior (GDELT→GNews), USPTO soft-fail due to API sunset, input format for `since`, and return structure. This significantly enriches behavioral expectations 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?

Opening with user-intent examples front-loads the purpose. Subsequent sentences compactly cover sources/fallbacks, date parsing, return shape, and the alternative tool — no filler. Dense 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 tool with three heterogeneous sources, fallback behavior, date grammar, and a structured return, the description covers all operational aspects: source fan-out, failure modes (USPTO sunset, GNews fallback), input formats, and return fields. No output schema exists, so the description carries that burden—and it does.

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 detailed descriptions for all three parameters. The tool description largely repeats the schema's guidance (ISO/relative for `since`, ticker/CIK for `value`), adding no new semantic content. Baseline 3 is fair.

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-phrased queries and states it's a change feed for a company in a time window, fanning out to SEC, news, and USPTO. It explicitly contrasts with entity_profile, distinguishing it from a key sibling. Verb+resource+scope are specific.

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

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

Explicitly names entity_profile as the alternative for static profiles, and frames usage around temporal queries ('this week/month/quarter'). This is clear when-to-use guidance with a named alternative.

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

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

Discloses scoping (per-identifier), persistence behavior (authenticated persistent vs 24-hour anonymous), and storage format (key-value pair). This adds significant value beyond the annotations, which only provide safety hints. 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 sentences, each providing distinct information: purpose, when to use, storage/retention semantics, and complementary tools. No redundancy, and the core action is front-loaded in the first sentence.

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

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

For a simple two-parameter storage tool, the description covers purpose, usage, scoping, persistence, and complementary operations. No output schema exists, so return values need not be explained. The schema handles parameter validation, making the description contextually 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 already provides strong descriptions for both parameters (100% coverage). The description adds contextual meaning by framing them as a 'key-value pair scoped by your identifier' and by giving use-case examples that illustrate what to store. This slightly elevates it above the baseline.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb ('Save') and resource ('data'). It distinguishes from siblings by naming recall and forget for retrieval and deletion, and provides concrete examples of use cases.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and gives concrete examples. It also names alternatives ('Pair with recall to retrieve later, forget to delete'), making usage boundaries unambiguous.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds behavioral details: graceful degradation when LEI/FIGI enrichment is unavailable, cascading through multiple lookup endpoints, and explicit handling of unresolved identifiers. There is no contradiction with annotations.

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

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

The description is long but well-organized into sections with examples and bolded types. Every sentence adds value; the purpose is front-loaded. Given the tool's complexity (multiple entity types, multiple sources), the length is justified. Could be slightly more concise, but efficient overall.

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 effectively covers what is returned: CIK, ticker, LEI, FIGI, RxCUI, and unresolved identifiers. It details data sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm) and explains degradation behavior. For a multifunctional entity resolution tool, this is comprehensive.

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 greatly enriches parameter meaning. It explains accepted formats for company (ticker, CIK, ISIN, name) and drug (brand or generic), gives concrete examples like 'AAPL', '0000320193', 'CH0038863350', and describes ISIN-to-LEI mapping. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves a name to canonical/official identifiers. It gives specific verbs ('resolve', 'look up') and examples of user queries. It distinguishes from sibling tools by emphasizing it is the first step when you have a name but need an ID, and it replaces 2-3 manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides example queries and indicates that it replaces manual lookups, guiding when to use. However, it does not explicitly state when not to use or list alternative tools that might handle already-resolved entities.

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/non-destructive behavior. The description adds valuable context by revealing that it internally calls ai_visibility_check for each entity, ranks by score, and returns specific fields (score, confidence, signal density). This goes beyond annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core purpose, followed by mechanism, use case, and output. Every sentence adds distinct value (what, how, why, result) without unnecessary repetition. It's compact 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?

Given the lack of an output schema, the description appropriately explains the return format (ranked list with score/confidence/signal density). It also covers the probing mechanism and use case. The schema covers parameter ranges and defaults, so overall completeness is high, though it could briefly mention the 2-8 entity constraint or model selection in the description itself.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces entity semantics ('your brand + N competitors') but does not add new parameter details beyond what the schema already documents. The schema itself covers entity ordering and optional models/context, so no additional compensation is needed.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from the single-entity sibling ai_visibility_check. It also names the internal mechanism (probing with ai_visibility_check) and output (ranked list), leaving no ambiguity about the tool's function.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an illustrative query, effectively conveying when to use the tool. It doesn't explicitly name alternative sibling tools or state 'use this instead of ai_visibility_check', but the 'side-by-side' comparison implies multi-entity scenarios, giving sufficient context.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses fan-out behavior across external APIs, potential slow first measurement (5-30s), and graceful degradation via sources_failed. These are meaningful behavioral traits not captured by the annotations, and nothing contradicts the declared safety profile.

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

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

The description is longer than typical but every sentence carries substantive information: purpose, sources, use cases, return structure, ecosystem scope, and failure behavior. It is front-loaded with the main purpose and follows a logical flow, though it could be trimmed slightly without losing meaning.

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

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

Given no output schema, the description thoroughly details the return value (summary block fields, per-advisory detail, links, alternative versions), the NPM-only scope, and partial-failure behavior. It fully equips an agent to predict outcomes and handle edge cases, making it highly complete for a composite tool of this complexity.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description reiterates that package is an npm name and version defaults to latest, but adds only minor context (e.g., scoped packages accepted) which is already present in the schema. No additional semantic depth is provided beyond what the schema already states.

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

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

The description opens with a specific composite purpose ('should I add this npm package to my project' check in ONE call) and enumerates exactly what sources and metrics are aggregated (deps.dev license/advisories/version history, bundlephobia bundle size/dependency count/ESM/tree-shake). This clearly distinguishes it from sibling tools like scan_competitor_ai_presence and deps.dev:version.

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

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

Explicit trigger language is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states the ecosystem boundary (NPM only in v1; other ecosystems go directly to deps.dev:version), providing a clear alternative path and when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds only that it returns 'matching jokes with IDs and text,' which is a minor behavioral detail. It does not disclose any additional constraints (e.g., pagination, ordering, or filtering nuances) beyond what annotations and the schema already provide.

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

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

The description is two short sentences, each earning its place: the first states the action, the second states the output. There is no redundant information or filler. It is efficiently front-loaded and easy to scan.

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 search tool, the description is complete. The output schema exists, so return values are documented elsewhere. Annotations cover the operational safety (read-only, idempotent). The tool has only two parameters, both self-explanatory via the schema. No additional context (e.g., authentication, rate limits) is needed for this straightforward read operation.

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

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

The schema has 100% parameter description coverage: both 'query' and 'limit' are described. The description's phrase 'by keyword or topic' essentially rephrases the 'query' parameter without adding new meaning. Since the schema carries the full semantic weight, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search dad jokes by keyword or topic.' The verb 'search' combined with the resource 'dad jokes' is specific, and the output of 'matching jokes with IDs and text' clarifies what is returned. This implicitly distinguishes it from sibling tools like 'get_joke' (retrieve a specific joke) and 'random_joke' (get a random joke), making the purpose unambiguous.

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

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

The description clearly conveys the tool's context: use it to find jokes based on a keyword or topic. However, it does not explicitly mention alternatives or exclusions (e.g., 'for a specific joke, use get_joke'). The verb 'search' provides enough contextual cue for when to use this tool, but without explicit sibling differentiation, 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?

Even with annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral detail: it returns 'character offsets and similarity scores,' uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows,' and discloses the '200K chars cap (longer inputs are truncated and flagged).' This goes well beyond the annotations and gives the agent concrete expectations about output and failure modes.

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

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

The description is dense but every sentence earns its place: it explains the operation, the use case, the pairing, and the technical implementation in three sentences. It front-loads the core action and then adds necessary context. There is no filler or repetition.

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

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

The tool has 3 parameters and no output schema, but the description covers all essential context: what input to provide (already-fetched text), how the algorithm works (embeddings, windows), what output to expect (passages with offsets/scores), and the truncation limitation. It also addresses the workflow with a sibling tool. This is fully complete for an agent to decide whether 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%, so the baseline is 3. The description reinforces the text parameter ('text you already pulled') and the query parameter ('natural-language query') but does not add new meaning beyond what the schema already provides. It does not explain the limit parameter beyond the schema, but the schema itself is fully descriptive, so 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+resource: 'Semantic search INSIDE a fetched record,' which clearly states what the tool does. It distinguishes from siblings by emphasizing 'inside a fetched record' and contrasting with 'ask_pipeworx_grounded' (fetch with the gateway, then ground over relevant passages). The scope is unambiguous.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt,' and provides a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' It also implies when not to use it (when the text fits in the prompt) and names a sibling tool, giving clear decision 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 indicate a non-read-only, non-destructive, idempotent operation. The description adds critical context: OAuth requirement (anonymous can't persist), delivery channel behaviors (feed always on, email/SMS optional), phone verification constraint, and webhook auto-disable after 10 consecutive failures. It also discloses return of subscription id and one-time webhook secret, going well beyond the annotation hints.

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

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

While longer than average, every section serves a purpose: core creation, requirements, type catalog, and delivery details. Information is packed into structured clauses and examples. It could be slightly trimmed, but there is no fluff or redundant wording.

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

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

Given the complexity (nested params, multiple types, delivery channels, no output schema), the description covers prerequisites, type-specific filters, return behavior (subscription id, one-time webhook secret), and operational details (auto-disable). It is a self-contained description that leaves no critical gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds semantic value by explaining type-specific parameters, e.g., items:["5.02"] as officer change, and providing concrete examples for each subscription type. It also clarifies delivery constraints (SMS must match verified phone, 10/day cap) that enrich the schema, making it more than repetition.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (Create) and identifies the resource (subscription to event stream) with clear scope. It also distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and enumerates supported types, leaving no ambiguity.

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

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

The description states this is for proactive monitoring and contrasts with pulling via recent_alerts or GET registry.pipeworx.io/alerts.json, implying subscription is for push-based monitoring. It also requires a Pipeworx OAuth account, clarifying prerequisites. It doesn't explicitly list when not to use, but provides clear context and alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds context about return shape (category-bucketed example questions with tool+argument shape) and that it comes from a live catalog, which is useful beyond the annotations. No contradiction, but it doesn't disclose any limitations or failure modes.

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

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

The description is longer than the ideal, but it is well-structured: leading with example user questions, then describing the output, then call variants and usage priority. Every part earns its place for an onboarding tool, though it could be tightened slightly.

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

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

With a single optional parameter, no output schema, and strong annotations, the description leaves nothing important uncovered. It explains what the agent gets, how to use it, and when to use it, making it highly complete for the tool's simple nature.

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

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

The schema already covers the single optional 'topic' parameter with 100% coverage. The description adds valuable context by showing example values ('finance', 'pharma', 'betting') and explaining the omit-for-full-spread behavior, going beyond mere schema repetition.

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

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

The description clearly states the tool's function: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shapes. It distinguishes itself from siblings by explicitly mentioning 'meta-tools' and positioning itself as the first stop, which separates it from ask_pipeworx and discover_tools.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also specifies call patterns: no arguments for full spread, or pass topic to focus, with a list of example topics.

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, it discloses that the row is deactivated rather than deleted, explaining the non-destructive behavior and its impact on historical data. Ownership enforcement is also a behavioral detail not present in annotations, adding meaningful 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?

Three sentences cover purpose, ownership, and deactivation behavior with no extraneous words. Each sentence adds distinct, necessary information, and the main action 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?

Given the simple one-parameter tool, the description covers the action, constraint, and side effect on historical data. Annotations and schema handle safety and parameter details, leaving no critical gaps.

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

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

The schema already fully describes the id parameter (uuid returned by subscribe). The description adds the semantic constraint that the id must belong to the user's own subscription, clarifying valid input beyond the schema.

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

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

The description opens with 'Cancel a subscription by id,' which clearly states the verb (cancel), resource (subscription), and how it's identified (id). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancel action and the deactivation 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?

It explicitly states a when-not condition: 'you can only cancel your own subscriptions,' clarifying the ownership boundary. It also mentions that historical events remain available via recent_alerts, offering an alternative for post-cancellation access to related data.

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

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

Even with annotations already indicating read-only and idempotent behavior, the description adds crucial operational context: the meaning of each verdict, especially the distinction between 'could_not_verify' (check did not happen, must not be used as evidence) and 'unsupported' (no source covers it). It also discloses the verification pipeline, error handling, and the guarantee of verbatim evidence with citations.

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

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

The description is dense but well-structured: it opens with trigger phrases, defines the use case, explains routing, lists verdicts, and adds a warning about a specific error case. It is longer than minimal but every section carries meaningful information. Slightly verbose in the middle but justified by the tool's complexity.

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

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

With no output schema, the description needs to explain return values and edge cases, and it does. It covers the verdict list, the evidence/citation format, the meaning of error states, and the routing logic across claim types. This is complete for a tool of this complexity, even including caller guidance about 'could_not_verify'.

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

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

The input schema already provides 100% coverage for both parameters (claim and tolerance_pct) with clear descriptions. The tool description adds some context about exact percent-delta math and the default tolerance cap, but does not substantially enhance the parameter-level meaning beyond what the schema already states. This matches the baseline of 3 for full 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 identifies the tool as a natural-language claim verifier that returns verdicts like confirmed/refuted, with specific verbs ('fact check', 'verify the claim') and a resource ('authoritative sources'). It distinguishes itself from sibling tools by describing a fast path for company-financial claims and a grounded fallback for other factual claims, plus a note that it replaces 4–6 sequential calls.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for financial vs. other claims. However, it does not explicitly name alternative sibling tools or specify when NOT to use this tool in favor of another, so it falls just short of a 5.

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