jikan

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 valuable behavioral context beyond the annotations: the default Workers AI call is free, while Anthropic calls require a BYO API key and are billed directly to the user by Anthropic. This cost/privacy nuance is useful and not inferred from the annotations.

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

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

Three sentences, front-loaded with the core action, then details on models and return shape, then use cases. No fluff; each sentence earns its place. The structure is exemplary for a tool description of this complexity.

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

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

For a 4-parameter tool with no output schema, the description covers the essential points: what it probes, how scoring works, default vs. optional model, return structure, and common use cases. It doesn't detail the 'combined view' or explain failure modes, but given the rich schema and annotations, it is sufficiently complete for an agent to 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% and each parameter has a thorough description. The tool description adds minimal extra information: it repeats the 'free default' and BYO key concepts already present in the schema. Since the schema already documents params well, the description provides only marginal value here, 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 opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx (which answers questions) and scan_competitor_ai_presence (which focuses specifically on competitor presence). The scope and output are 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 explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model with an option to use Anthropic by passing a key. It does not name alternatives or state when not to use it, but the context is clear enough to guide appropriate selection.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds rich behavioral context: it routes to one of 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. It also clarifies that it covers live news and news-feeds packs. This goes well beyond the annotations and provides valuable operational insight.

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 highly structured: it opens with a strong directive ('PREFER OVER WEB SEARCH'), then explains capabilities, provides examples, and closes with differentiation from siblings. Every sentence adds value, but it could be tightened slightly without losing key guidance. Still, it earns a 4 for its purposeful structure and front-loaded key message.

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

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

Given the tool's complexity as a multi-tool router, the description is exceptionally complete. It covers domains, examples, alternatives, return format (structured answer with citations), performance characteristics (one fast call), and scope of sources. No output schema exists, but the description sufficiently communicates what the caller should expect. This tool is fully contextualized.

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

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

Schema description coverage is 100%—the 'question' parameter and its aliases are fully documented. The description doesn't add new parameter semantics beyond showing examples of valid questions, which is helpful but not essential. Per calibration, baseline 3 is appropriate when schema fully covers parameters.

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

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

The description clearly defines the tool as a question-answering router with a specific verb+resource: 'ask Pipeworx' routes questions to the right tool among 5,529 tools across 1,455 sources and returns structured answers with citations. It distinguishes itself from siblings by comparing against ask_pipeworx_grounded and deep_research, and explicitly positions itself as the default entry point ('START HERE').

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

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

The description provides explicit when-to-use guidance with a long list of example domains (SEC filings, FDA data, FRED/BLS, etc.) and trigger phrases ('what is', 'look up', 'find', 'get the latest'). It also gives explicit when-not-to-use and alternatives: step up to ask_pipeworx_grounded for hallucination-resistant single answers or deep_research for broad/multi-part questions. This exceeds minimal guidance.

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

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

The description discloses the beta nature, that no candidate is currently active (matching ask_pipeworx exactly), and that results are compared against the stable router. This adds substantial context beyond the annotations (readOnlyHint, idempotentHint) and clarifies the experimental edge without any contradiction.

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

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

The description is four focused sentences, front-loaded with 'Beta version,' and each sentence adds value: clarifying identity, current state, usage, and fallback behavior. It is information-dense 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?

Given no output schema, the description compensates by referencing the 'same response shape' as ask_pipeworx. It fully explains the beta road map, current parity with stable, and that it is a full working router, making the tool's behavior complete for an agent.

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

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

Schema coverage is 100%, with all parameters clearly described as aliases for 'question.' The description mentions 'same arguments' but adds no extra semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable router by noting the candidate routing improvements, making its purpose unmistakable.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear when-to-use. While it doesn't explicitly name an alternative for when not to use it, the contrast with the stable router is implied, and the sibling list includes ask_pipeworx.

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

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

The description adds substantial behavioral context beyond the annotations. It explains the internal routing (same as ask_pipeworx), the grounded extraction mechanism, the exact success and refusal response shapes, and the extra LLM call cost. None of this is available in annotations, so it carries the full burden and does so thoroughly. 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 dense but every sentence earns its place. It front-loads the key differentiator (hallucination-resistant), then explains the mechanism, response formats, use cases, and cost trade-off. There is no filler or redundancy. It is well-structured 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?

Despite lacking an output schema, the description fully explains return values, failure modes (refusal reasons), and usage context. It even covers performance trade-offs (extra LLM call). For a tool with this complexity, the description provides complete context for an agent to decide when and how to invoke it.

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

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

The input schema has 100% coverage with all aliases described, so the baseline is 3. The description does not add additional parameter-level information, but it doesn't need to since the schema already documents the 'question' parameter and its aliases clearly. The description's focus is on behavior, not parameters, which is acceptable given the schema's completeness.

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: a hallucination-resistant answer mode that extracts answers using only tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior. The verb 'EXTRAct' and the resource (answer from tool results) are specific and unambiguous.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' It also names the alternative, ask_pipeworx, and gives a when-not-to-use: 'prefer ask_pipeworx for casual lookups.' This is a textbook example of clear usage guidelines.

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

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

Adds extensive behavioral context beyond readOnly/idempotent annotations: parallel fan-out, resolver contract with match_confidence, suppression of analysis on low-confidence matches, market_closed_or_inactive status, wide-spread tradeability flag, and cancellation-rule risk parsing. This is a model of 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?

Long (400+ words) but heavily structured with section headings in caps, classification lists, fan-out examples, and response shapes. Every paragraph adds distinct information. Slightly over-long but justified by tool complexity; front-loaded with purpose and usage.

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, description provides comprehensive coverage: return shapes for result.market/analysis/evidence, resolver contract, parent_event extractor, news fallback fields, safety short-circuits, and resolution-rule risk. No significant gaps for an agent to misuse the tool.

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

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

Schema covers 100% of parameter descriptions (market accepts slug/URL/question, depth enum with default, include_raw with size implications). Description reinforces but doesn't materially extend parameter semantics beyond 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?

Clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Explicitly differentiates from siblings by focusing on resolving a single market and returning evidence packet + market-vs-model comparison. Distinguishable from polymarket_arbitrage/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?

States explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides fan-out examples. No explicit when-not or alternative tool names, but context is clear.

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

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

Annotations already mark it read-only/idempotent, but the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, parallel execution, and citation URIs. No contradiction with annotations.

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

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

The description is information-dense and well-structured, starting with trigger phrases and core function, then entity-specific details, and ending with output format. While longer than two sentences, every sentence adds value and no content is redundant.

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

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

For a tool with no output schema, the description explains return values ('paired data + citation URIs') and sorting behavior. It covers both entity types and common use cases, though 'paired data' could be more explicit about the exact response format. Overall, sufficient for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with baseline descriptions, but the description enriches meaning by detailing what metrics are pulled for each type. For example, type='company' pulls 10-K revenue and net income, while type='drug' pulls FAERS counts. This goes beyond the schema's simple enum and array 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 explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in a single call, with specific metrics for each type. It distinguishes itself from siblings by saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' making the purpose unmistakable.

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

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

Provides concrete trigger phrases such as 'Compare X and Y' and 'which is bigger/better/larger,' and clearly instructs to prefer this over sequential single-pack lookups. The description also specifies when to use type='company' vs type='drug', giving both 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?

With annotations declaring readOnly/openWorld/idempotent, the description adds substantial behavior: it is NOT open-web search, it never invents answers and returns gaps[], it can re-angle via second-hop, includes contradictions scans, semantically excerpts large records, and even discloses expected latency (15-90s). This goes well beyond annotation hints without contradicting them.

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

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

The description is long and dense, but it is front-loaded with the critical account requirement and alternative-tool guidance. Each sentence contributes meaningful operational detail needed for such a complex tool, though a bit more structural formatting (e.g., separation of concerns) would improve readability.

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

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

Given there is no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers prerequisites (account, paid depth), timing, and iteration behavior, making it highly 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 baseline is 3, but the description enriches the depth parameter with practical constraints: thorough requires a paid plan, standard/thorough add gap-recovery hops, quick is single-hop. It also clarifies that the question can be broad and multi-part, adding meaning 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 performs grounded multi-source research across 1,455 structured data sources, decomposing questions into facets and routing them to 5,529 tools in parallel. It explicitly distinguishes itself from ask_pipeworx and open-web search, making its purpose and scope unambiguous.

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

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

It provides explicit when-to-use guidance: best for broad/multi-part structured-data questions, and explicitly alternatives for single lookups (ask_pipeworx) and breaking/current-news topics (ask_pipeworx). It also notes the account and paid-plan requirements, telling agents to use ask_pipeworx if not signed in.

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 useful behavioral traits beyond the annotations: it returns top-N results with names, descriptions, and full input schemas, and results are directly callable without a second schema lookup. This adds meaningful context about output format and efficiency, while annotations already cover the read-only/idempotent nature.

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

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

The description is well-structured and front-loaded: it starts with purpose, then when-to-use, output details, and a final usage directive. While it contains a long list of domains, each item is informative for the user, and every sentence serves a distinct function. It is slightly verbose but appropriately so.

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

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

The tool is a discovery/search tool with one required parameter, and the description explains its return value (top-N tools with schemas and examples) despite lacking an output schema. It covers usage context, exclusions, and domain range, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear parameter descriptions including aliases and examples. The description adds domain examples and mentions 'top-N', but the schema already documents the 'limit' parameter. Thus it doesn't add significant meaning beyond the schema, warranting the baseline score.

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

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

The description uses a specific verb ('Find tools') and resource ('tools'), and explicitly lists the domains it covers, distinguishing it from sibling tools like search_within or deep_research which search data rather than discover tools. The phrase 'Call this FIRST when you have many tools available' further clarifies its unique role.

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

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

It provides clear context for when to use ('Use when you need to browse, search, look up, or discover what tools exist for...') and includes an exclusion ('not just one answer') indicating it's for exploring the option set. However, it does not explicitly name alternative tools to use instead, stopping short of the top score.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive. The description adds substantial operational detail: cross-source fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific return fields; patent API sunset soft-fail; GDELT→GNews fallback; and the zero-padded CIK requirement. 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 front-loaded with example queries and the core value proposition. The detailed return field list, fallback notes, and caveats are necessary for a tool with no output schema. A few clauses could be tightened, but every sentence carries useful information.

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

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

Given no output schema, the description thoroughly covers return values (cik, filings, fundamentals, patents, news, LEI), input requirements, and caveats (patents sunset, name unsupported). It is sufficient for an agent to select and invoke the tool correctly without ambiguity.

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%: both parameters have thorough descriptions including examples and the resolve_entity hint. The description's parameter guidance ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') exactly echoes the schema text, adding no new semantic information. 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 explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' and provides concrete example queries ('Tell me about X', 'research Acme'). It distinguishes from siblings by noting it should be preferred over chaining single-pack lookups and pointing to resolve_entity for name-only inputs.

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 ('ALWAYS PREFER ... when the user asks for a holistic view') and when not to (names not supported, use resolve_entity first). It also contrasts with single-pack SEC/XBRL/news lookups, giving clear context for selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' matches this. The description adds use cases like clearing sensitive data but no additional behavioral details beyond annotations; 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?

Two sentences, front-loaded with the primary action in the first sentence followed by concise usage guidance. Every word earns its place, no redundancy.

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

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

For a simple one-parameter deletion tool with annotations covering safety and idempotency, the description fully covers purpose, usage scenarios, and sibling relationships. No output schema is needed, so no gaps.

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

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

The input schema fully documents the required 'key' parameter with type and description 'Memory key to delete' (100% coverage). The description only adds 'by key' and 'previously stored', which does not materially enhance the schema's meaning.

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

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

The description uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key', clearly distinguishing this from sibling tools like remember and recall which store/retrieve memories. 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?

Explicitly states when to use: 'context is stale, the task is done, or you want to clear sensitive data'. It also names related tools ('Pair with remember and recall'), giving clear integration context and sibling differentiation.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits a single text blob ready for site-root placement. This goes beyond the annotations without contradicting them.

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

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

The description is appropriately sized: one core sentence, one process sentence, one output sentence, and a short use-case list. It is front-loaded with the main purpose and every sentence earns its place 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 read-only utility with clear schema and annotations, the description fully covers what the tool does, how it works, the output format, and when to use it. The standard llms.txt format is known, so no further output explanation is needed.

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

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

The input schema already describes both parameters thoroughly (URL and max_links with default/max). The description does not add significant semantic detail beyond the schema, simply referencing 'any URL' and 'key links' without further parameter context. With 100% schema coverage, 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 a specific verb ('Generate') and resource ('llms.txt file for any URL'), and explains the process (fetches page, extracts metadata, emits markdown). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on llms.txt generation rather than general AI visibility scanning.

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

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

Provides explicit use 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'), which clearly indicate when to use. However, it does not mention when not to use or explicitly compare to alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description adds behavioral context by listing the returned data (score, synopsis, genres, studios, episode count, and more), which goes beyond the annotations and helps set 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 a single sentence that front-loads the verb and purpose. It contains zero filler and every phrase earns its place. Ideal conciseness for a simple 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?

For a tool with only one parameter, an output schema, and comprehensive annotations, the description is sufficient. It states what the tool returns, and the output schema covers detailed return structure. No significant gaps remain.

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

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

The schema description coverage is 100%: the only parameter 'id' is fully documented with a detailed explanation and examples. The description merely repeats 'by ID' without adding any syntax, format, or constraint details beyond 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 uses a specific verb+resource: 'Get full details for an anime by ID.' It clearly states the operation (get details), the resource (anime), and the scope (by ID). This distinguishes it from siblings like search_anime (query-based) and top_anime (list).

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

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

The description clearly implies the use case: when you have an anime ID. However, it does not explicitly mention alternatives or when not to use this tool, such as 'use search_anime for name-based lookup.' The context is clear but lacks 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 mark the tool as read-only, idempotent, and non-destructive. The description adds context (returns active subscriptions, includes fields), which aligns with annotations. No contradiction; additional behavioral context is 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?

Two concise sentences that front-load the action and resource, then provide return fields and usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete: it names return fields, states scope, and gives real-world usage context. Annotations cover safety, and sibling tools clarify ecosystem placement.

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

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

The single parameter (include_inactive) is fully documented in the schema with a clear description, achieving 100% schema coverage. The description adds no further parameter semantics, which is acceptable given the schema's completeness.

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

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

Description states a specific action ('List the caller's active subscriptions') with a clear resource and scope (active vs inactive). It also lists return fields, making the tool's function unambiguous and distinct from siblings like subscribe/unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This guides when to use the tool, though it doesn't explicitly name alternatives or 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 are all false, so no prior safety profile. The description adds valuable behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, returns a claim_token when filing without an account, and how to use it later to check status. It also clarifies the review cadence ('digests daily'). 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 long, every sentence provides distinct operational guidance. It's front-loaded with the core purpose, then usage rules, caveats, and mechanics. No redundant sentences, though it could be slightly tighter.

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

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

The description covers purpose, when-to-use, boundaries (Pipeworx-only tools), content guidelines (don't paste user prompt), claim_token mechanics, rate limits, and cost. Given there is no output schema, it explains the key return value (claim_token) sufficiently. Slight gap: doesn't specify the exact response format when no claim_token is issued, but it's not essential.

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

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

Schema descriptions cover 100% of parameters with detailed explanations (e.g., claim_token says 'with no other arguments'). The description reinforces claim_token usage but doesn't add new syntax beyond schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly establishes the tool's purpose and differentiates it from siblings like ask_pipeworx and discover_tools. The title aligns perfectly.

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 lists when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also explicitly excludes other MCP servers: 'if the tool came from a different MCP server... file it with that server instead.' This 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This explains data provenance, privacy, and caching behavior, enriching beyond the structured metadata.

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

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

The description is well-structured and front-loaded with the core action, then lists use cases with numbered points, and ends with caching/privacy details. It is slightly verbose but every sentence adds meaningful information. The use cases and caveats are concise and earn their place.

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

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

For a simple read-only tool with one parameter, the description is highly complete. It explains the return values (top tools, top packs, total call volume), the aggregation source, lack of PII, and caching behavior. Since there is no output schema, the description adequately covers what the agent needs to know without missing critical aspects.

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

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

Schema coverage is 100% and the parameter description in the schema already explains the window enum, including the distinction between short and long windows. The tool description repeats the window options but does not add new semantic detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb ('returns') and identifies the resource ('top tools, top packs, total call volume'). The use cases further distinguish it from sibling tools like discover_tools by focusing on current popularity and canonical choice, not just discovery.

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

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

The description provides explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice before asking your own question,' and 'seeing whether your use case aligns with what most agents need.' It does not explicitly contrast with alternatives or state when not to use it, but the situational guidance is clear and actionable.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent). It details internal logic: monotonicity checks, partition-sum validation, semantic anchoring with Jaccard threshold, placeholder filtering, and the fill-check distinction between theoretical and realizable edge. It even cautions not to trade when realizable_edge_pp ≤ 0. 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-structured with ALL-CAPS section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it skimmable. It front-loads the core purpose and usage. Some redundancy exists (e.g., repeating 'partition_check' details), but overall it earns its length for a complex 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?

Given the tool's complexity, no output schema, and rich parameter behavior, the description fully covers response formats ('opportunities[]', 'partition_check{...}'), edge cases (placeholder slugs, low similarity, thin legs), and fill-check pricing. It leaves no significant gap for an agent to misuse the tool.

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

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

Although schema coverage is 100%, the description enriches both parameters with concrete examples ('fed-decision-may-2026' for event, 'Strait of Hormuz traffic returns to normal' for topic), explains what each mode does, and clarifies that parameters are optional (NO args for trending scan). This adds meaning well beyond the schema.

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

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

The description opens with a clear, specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by explicitly naming those tools for related but different purposes.

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

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

Provides explicit guidance on when to use each mode ('Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)') and names an alternative for custom sizing ('For custom sizing use polymarket_fill_risk'). It doesn't explicitly contrast with all siblings, but the mode guidance is strong.

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

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

Annotations already declare read-only and idempotent behavior, and the description adds extensive behavioral context: response segments, diagnostics for empty segments, caching (1h), edge net of slippage, 24h-move warnings, partition Kelly quirks, and placeholder filters. There is no contradiction with annotations; this is rich disclosure beyond the structured fields.

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 an extremely long, dense block of text (over 700 words) with many parenthetical implementation details (e.g., specific α values, GDELT ratios, historical gate relaxations). While it uses labeled sections, it is not concise and would overwhelm an agent. The length is disproportionate to the invocation need, and much of the detail could live in documentation or an output schema.

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

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

Without an output schema, the description takes full responsibility for explaining return values. It does so thoroughly: top-level keys by_segment, fed_candidates/fed_note, _diagnostics with funnel counters, and the fields on each opportunity (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume). It also explains caching and why segments may be empty. This is complete for a tool of this complexity.

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

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

The input schema covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The main description adds valuable inter-parameter semantics, such as how min_kelly skips partition arbs because they return kelly_fraction_half=0 by design and how min_partition_leg_kelly applies per-leg. This exceeds what the schema alone provides.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly identifies the tool's purpose and differentiates it from siblings like polymarket_arbitrage by emphasizing the Pipeworx data source and the built-for use case of 'what should I bet on today'.

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 ('Built for what should I bet on today') and highlights the benefit of not paging hundreds of markets. It also gives guidance on knobs and caveats like the unreliability of Fed bets. However, it does not name alternative tools or explicitly state when not to use it, so it lacks explicit exclusion guidance.

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

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

Despite annotations marking it read-only/idempotent, the description adds substantial behavioral detail: snapshots are written only on cache-miss, history is bounded by 60-day TTL, decay is computed on daily closes of edge_pp_net net of default slippage, and missing snapshot dates mean no scan occurred. These limitations are not visible in annotations and significantly shape expected behavior.

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

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

The description is long but efficiently organized with labeled sections (Args, RESPONSE, LIMITS). Every sentence adds operational or semantic detail, from the psychological rationale to the TTL limitation, with no filler.

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

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

For a read-only telemetry tool with no output schema, the description thoroughly documents the response shape (tracked[], expired[], snapshot_dates[]), field meanings, and edge cases. It also explains the data source and limitations, making it fully actionable for an agent.

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

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

The schema already documents both parameters with defaults and ranges. The description adds the 'snapshot family' concept and the max-30 lookback bound, and it explains how parameters affect the response (latest snapshot vs prior snapshots). This is modest added value beyond the 100% 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 states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. This clearly differentiates from sibling polymarket_edges, which likely reports current edges, by focusing on temporal persistence and decay.

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

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

It provides clear context by framing when edge age matters ('a fresh wide edge and a 3-week-old wide edge are different trades') and what questions it answers. It does not explicitly name alternatives or exclusions, but the purpose strongly implies use for historical edge analysis rather than current edge discovery.

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

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

Adds rich behavioral context beyond the readOnlyHint/idempotentHint annotations: 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), explains basket mechanics with theoretical_sum vs realizable_sum, and warns that 'partial basket fills convert an arb into an unhedged directional position.' This deeply informs the agent about the tool's execution and risk 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 front-loaded with the core purpose, then clearly separated into SINGLE-MARKET and BASKET blocks. It is dense but every sentence carries essential information for a complex dual-mode tool, with 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?

With no output schema, the description properly enumerates all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, thin_legs[], forced_directional_risk, etc.) and interprets them. Combined with explicit usage triggers and sibling context, the description fully equips an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds critical mode-dependent semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S (shares per leg)' in basket mode. Side defaults are also clarified for both modes, going far beyond the schema descriptions.

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

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

The opening line 'Realizable-vs-theoretical edge check against live CLOB order-book depth' precisely states the tool's function. It distinguishes from siblings like polymarket_arbitrage by explicitly positioning itself as the pre-trade risk check, saying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal.'

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: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also details both modes (single-market and basket) with exact parameter requirements, leaving no ambiguity about invocation context.

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

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

Annotations already declare readOnly/idempotent behavior, lowering the burden, but the description adds deep behavioral transparency: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the explicit caveat that pre-mapped ≠ tradeable. It openly explains when spreads are meaningless across temporal gaps.

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 (modes, response, safety fields) and every sentence adds necessary context for this complex tool. The opening sentence is front-loaded with the core purpose, and the length is justified by the tool's sophistication.

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 thoroughly explains the response shape, including leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment, and skipped comparison counters. It covers edge cases and failure modes comprehensively for a cross-venue comparison tool.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by listing the topic enum values and explaining the override behavior between topic and explicit kalshi_event_ticker/polymarket_event_slug. It clarifies that explicit parameters override topic mappings, which the schema alone does not convey.

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

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

The description clearly identifies the tool's function: calculating cross-venue spread between Kalshi and Polymarket for the same resolving question. It differentiates from sibling tools by describing two modes, output contents, and safety fields, making the purpose unambiguous.

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

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

The description provides clear usage context by explaining both modes (topic shortcuts vs explicit ticker/slug) and warns when pre-mapped topics are not tradeable. It does not explicitly name alternative tools, but it gives strong when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds valuable behavioral context about scoping to anonymous IP, BYO key hash, or account ID, and that omitting the key lists all saved keys. 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?

Two well-structured sentences: first states the core action and the alternative list behavior, second gives concrete usage examples and pairing guidance. Every sentence earns its place with no redundancy or fluff.

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

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

Given the simple one-optional-parameter tool, strong annotations, and complete schema, the description fully covers usage, scoping, and relationship to remember/forget. No output schema is needed for a retrieval tool, and nothing important is missing.

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

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

Schema coverage is 100% and the key parameter already has a clear description ('Memory key to retrieve (omit to list all keys)'). The description repeats this and adds scoping context, but doesn't introduce new parameter-specific meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a previously saved value via remember, and also supports listing all keys when omitted. It distinguishes itself from sibling tools like remember and forget by explicitly pairing with them, and specifies the resource (saved memory values).

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

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

The description gives concrete usage context: looking up previously stored context like target ticker, address, or research notes, and notes scoping to identifier. It mentions pairing with remember/forget but doesn't explicitly state when not to use it or name alternatives, though the context is strong.

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

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

Annotation Contradiction: The annotations declare readOnlyHint=true, but the description explicitly states that setting mark_read:true flags returned events as read, which mutates state and affects subsequent calls. This directly contradicts the read-only annotation, making the behavioral disclosure inconsistent and unreliable.

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

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

The description is moderately sized and front-loaded with the core purpose. It covers return format, filtering, mark_read behavior, and external access in four sentences. A compact but complete summary, though it could be slightly tightened without losing essential information.

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

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

With no output schema, the description adequately describes return values (each event carries source, citation_uri, raw payload). It covers query parameters, side effects, and alternative access. It does not mention pagination or limit/unread_only defaults, but these are adequately documented in the schema, so completeness is high.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' example ('sec_8k'), the 'since' format (ISO timestamp), and the behavioral effect of 'mark_read' (next call shows only newer events). These enrich the parameter understanding beyond the schema.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clearly distinguishes itself from siblings like list_subscriptions by focusing on alert events rather than subscriptions. It also specifies the return content (source, citation_uri, payload), leaving no ambiguity about what the tool does.

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

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

The description provides clear usage context: it says polling works fine and mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts and dashboards. It does not explicitly name sibling tools to exclude, but the guidance on when to use and the external fallback gives practical direction.

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 mark this as read-only/idempotent, the description adds substantial behavioral context: it fans out to multiple sources in parallel, uses a fallback chain (GDELT preferred, GNews when rate-limited or 5xx), soft-fails for USPTO due to a known API sunset, and specifies that results include structured changes grouped by source with citation URIs. This greatly exceeds the annotation baseline.

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

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

The description is compact yet information-dense. It front-loads user-facing query examples, then covers source behavior, date syntax, output structure, and a sibling distinction—all in a single paragraph. Every sentence contributes new information 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?

Despite lacking an output schema, the description clearly states the return shape ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers fallback logic, known API limitations, and parameter syntax. For a multi-source aggregation tool, this is a complete and actionable specification.

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

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

The schema covers all three parameters with descriptions, but the tool description adds valuable semantics: 'since' accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y') and a recommended value ('30d' or '1m'); 'value' gets ticker/CIK examples; and 'type' is noted as only 'company' supported today. This enriches schema meaning.

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

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

The description opens with natural-language query examples and then states a specific function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It enumerates data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly differentiates from the sibling tool entity_profile, making the tool's 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 when-to-use signals via example phrasings ('What's new with X', 'latest on Y') and gives an explicit alternative: 'Use entity_profile instead when you want the static profile...' It also documents the fallback behavior for news sources, giving the agent guidance on expected data availability.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which align with the description. Additionally, the description adds context about session scoping and retention (24 hours for anonymous), going 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 three sentences, front-loaded with purpose, then usage, then persistence details. No wasted words; every sentence contributes.

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 2-parameter tool with no output schema, the description covers what, when, how, persistence, and how to retrieve/delete. It is fully complete for the agent to use 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% with clear descriptions for key and value. The description enriches this by providing example keys and explaining the key-value pair scope, adding value 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 uses a specific verb 'Save' and clearly identifies the resource ('data the agent will need to reuse later'). It differentiates from siblings like recall and forget by explicitly mentioning pairing, making it distinct.

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

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

It provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and mentions alternatives ('Pair with recall to retrieve later, forget to delete'). It also clarifies persistence conditions for authenticated vs. anonymous sessions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description adds significant value by disclosing that unresolved identifiers are listed under 'unresolved' rather than omitted, that each identifier is labeled with its source, and that LEI/FIGI enrichment degrades gracefully if external services are unavailable. This goes well beyond the structured annotations.

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

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

The description is fairly long but well-structured: it opens with user-phrase examples, then the key guidance ('Use FIRST'), then SUPPORTED TYPES with nested detail. Every sentence contributes valuable information without redundancy, though it is denser than strictly necessary for a 2-parameter 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?

Despite having no output schema, the description thoroughly explains what the tool returns (canonical identifiers, source labels, unresolved field) and its behavior across company and drug types, including graceful degradation and internal cascading calls. This is complete for the tool's complexity and clearly positions it against sibling tools.

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

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

The schema already covers both parameters with descriptions and an enum for type, so the baseline is 3. The description adds meaningful semantic detail: for 'company' it explains the full identity spine (CIK, ticker, LEI, FIGI) and accepted inputs (ticker, CIK, name), and for 'drug' it specifies RxCUI/ingredient/brand and RxNorm citation, enriching the bare schema definitions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers needed by other tools. It provides specific verbs ('resolve', 'look up') and resources (ticker, CIK, LEI, RxCUI, etc.), and distinguishes itself from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID.' The supported types and detailed outputs further clarify 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?

It gives explicit usage context: 'Use FIRST whenever you have a name but need an ID' and explains how it replaces multiple manual lookups. However, it does not explicitly state when NOT to use it or name alternative sibling tools (e.g., entity_profile, compare_entities), so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details beyond annotations: it reveals that it 'Probes each entity with ai_visibility_check', explains ranking behavior, and lists the return fields. Since there is no output schema, this return-format disclosure is valuable and transparent.

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 and packs in the core action, method, use case, and output format. It is front-loaded with the main purpose, contains no fluff, and every sentence adds value.

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

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

Given a moderately complex tool with 4 parameters and no output schema, the description covers all essentials: what it does, when to use it, how it behaves, and what it returns. It also clarifies entity ordering and context usage. 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?

Schema coverage is 100%, so all parameters have descriptions. The tool description adds meaningful semantics by explaining that the first entity in 'entities' is treated as the 'subject' and the rest as competitors, and by giving an example for the 'context' parameter. This goes beyond the schema, earning 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 purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (AI visibility), the action (compare/rank), and the output (ranked list with score, confidence, signal density). It also distinguishes from sibling tools by mentioning it probes with ai_visibility_check and handles multiple entities, unlike a single-entity check.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and gives an example question. It implies the tool is for multi-entity comparison, differentiating from ai_visibility_check which likely handles single entities. However, it does not explicitly mention when not to use it or alternatives like compare_entities, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts while the rest still returns. It also discloses the composite fan-out behavior, which is critical for understanding latency 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 front-loads the core purpose and use case, then proceeds through return values, ecosystem scope, and failure handling in logical order. Despite its length, it avoids fluff and maintains a tight, information-rich structure.

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

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

No output schema is provided, yet the description compensates by enumerating return fields: summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and recent alternative versions. It also covers timing (5-30s), partial failures, and ecosystem limitations. For a composite tool with this complexity, the description is complete enough for an agent to set expectations correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that 'package' accepts scoped packages like '@types/node' and that 'version' defaults to the latest published version. It also implicitly ties the version parameter to the 'recent alternative versions' output, giving more context than the schema alone. Not quite a 5 because the description doesn't elaborate on all edge cases, but it does add meaningful 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 a specific, actionable statement: "Composite 'should I add this npm package to my project' check in ONE call." It clearly names the resources (deps.dev, bundlephobia) and distinguishes this from sibling tools by focusing on npm package evaluation. It's unambiguous what the tool does and how it differs from general research tools.

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

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

The description explicitly says when to use it: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides an exclusion: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly," which guides the agent toward an alternative. This is clear, actionable guidance with alternatives covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by listing the returned fields (score, type, episode count, etc.), which goes beyond the annotations. 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 a single sentence that immediately states the action and results. No filler or redundant phrases; it is efficiently front-loaded.

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

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

For a simple single-parameter search tool with read-only annotations and a provided output schema, the description covers the essential purpose and return contents. It could mention pagination or result limits, but these are not necessary given the tool's simplicity and the presence of an output schema.

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

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

The schema fully documents the single 'query' parameter with description and examples (100% coverage), so the description does not need to add much. It does reinforce that search is by title, but adds no new semantic information beyond the schema.

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

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

The description clearly states the action ('Search for anime by title') with a specific resource and scope. It distinguishes itself from sibling tools like get_anime (likely fetching details for a specific anime) and search_characters (searching a different entity type).

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

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

The description implies usage for looking up anime by title, but it does not explicitly state when to prefer this over alternatives like get_anime or top_anime, nor does it mention exclusions. No sibling tool references or alternative conditions are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the return value details (character names, nicknames, favorites count, biography) and confirms the search action, which adds behavioral context beyond the annotations without contradiction.

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

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

The description is a single sentence that front-loads the verb and resource, then lists return fields. It is concise, efficient, and contains no filler.

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

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

For a simple one-parameter search tool with rich annotations and an output schema, the description sufficiently covers what the tool does, what it returns, and how to use it. The presence of an output schema means return format details are handled elsewhere.

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 a clear description for the 'query' parameter ('Character name to search for (e.g., "Naruto")') and examples. The tool description reinforces the 'by name' aspect but doesn't add additional semantics beyond the schema.

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

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

The description clearly states a specific verb and resource: 'Search for anime/manga characters by name.' It also lists return fields (names, nicknames, favorites count, biography), which adds precision and distinguishes it from sibling tools like search_anime.

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

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

The description provides clear context for when to use (when searching for characters by name) but does not explicitly mention alternatives or exclusions. It's unambiguous enough that the agent can infer usage, though it doesn't name sibling tools like search_anime or resolve_entity.

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, non-destructive, idempotent. Description adds substantial behavioral detail: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flagging, and return offsets/similarity scores. 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?

Two dense but purposeful sentences: first defines the operation, second gives usage guidance, third covers technical specifics. Every sentence earns its place with zero 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?

No output schema, but description covers inputs, return shape (top-N passages with offsets and scores), truncation behavior, and use-case context. Fully complete for an agent to select and invoke confidently.

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 3. Description adds contextual meaning beyond the schema by framing 'text' as already-fetched record content (SEC 10-K, article) and providing query examples, plus confirming the limit default. This extra context raises it a point.

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 a specific verb+resource: semantic search inside a fetched record. It distinguishes from siblings by emphasizing 'inside' an already-pulled text and by contrasting with grounding over the whole document.

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

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

Explicitly says when to use ('too big to cram into the prompt') and names an alternative pattern ('Pairs with ask_pipeworx_grounded'). Provides context-saving rationale and exclusion from whole-document grounding.

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 account requirement, delivery channel options, SMS verification and daily cap, and always-on feed behavior beyond annotation flags. No contradiction with annotations (idempotentHint, readOnlyHint, destructiveHint).

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

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

Description is compact and front-loaded with the core action and return value. Each sentence adds relevant detail—prerequisites, type examples, delivery constraints—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?

Covers return value, prerequisites, delivery options, and constraints, making it self-sufficient for basic usage. Omits webhook delivery channel, but the schema fully documents it. Overall, a thorough description for a complex tool.

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

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

Schema already documents all parameters at 100% coverage, so baseline is 3. Description adds semantic value with examples (sec_8k item codes, polymarket topic, clinical trial requirements) that aid in choosing the right param structure.

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

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

Clearly states the action (create), resource (proactive monitoring subscription), and return value. The list of supported types and delivery channels further clarifies scope, distinguishing it from sibling subscription management tools like list_subscriptions and unsubscribe.

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

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

Implies usage for persistent, event-driven monitoring. Provides prerequisites (OAuth account) and hints at an alternative access method (feed via recent_alerts). Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, so the description does not need to restate safety. It adds useful behavioral context by describing the return content (category-bucketed examples, live catalog, exact tool + argument shape) and the no-arguments vs. topic-filtered call modes. 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-structured and information-dense. It front-loads the purpose with questions, then covers output, parameter usage, and when to call. Every sentence contributes value; the length is justified for an onboarding 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?

Given the tool's low complexity (one optional parameter, no output schema) and strong annotations, the description is complete: it explains what will be returned, how to call with or without topic, the category list, and when to use the tool first. No missing critical context.

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

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

Schema coverage is 100% and the input schema already documents the topic parameter and its allowed values. The description adds only minor reinforcement ('full spread' vs. focus, example values like 'finance' and 'betting') without introducing new semantics, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape for each. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by positioning itself as the 'first' call when you do not know what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and 'or to learn how to call the meta-tools'. This gives a clear when-to-use instruction and implies it should precede other tools, though it does not name specific alternatives to avoid.

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 annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's safety burden is low. The description adds the behavioral detail that the tool returns titles, scores, and rankings, and that the type filter is optional, which provides some context beyond the annotations. It does not disclose any hidden side effects or limitations, but the annotation coverage makes this acceptable.

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

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

The description is a single, front-loaded sentence that efficiently conveys the purpose, filter, and return data. Every word contributes to the agent's understanding, with no fluff.

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

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

Given the simple shape (one optional parameter), strong annotations, and presence of an output schema, the description is complete. It covers the key aspects: what the tool does, the filter, and the return type. No critical information is missing for a list-style tool.

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

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

The schema provides 100% coverage for the single 'type' parameter, including allowed values and the fact that it's optional. The description restates examples but doesn't add meaning beyond the schema. Therefore 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 uses the specific verb 'Get' with the resource 'top-ranked anime', clearly distinguishing from sibling tools like search_anime or get_anime. It also describes the optional type filter and the returned fields (titles, scores, rankings), making the tool's 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 indicates the use case: fetching top-ranked anime. It explains the optional type filter, which tells the agent when to include a type parameter. However, it doesn't explicitly name alternatives or state when not to use this tool, so the guidance is clear but not fully differentiated.

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

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

Beyond annotations, the description discloses ownership enforcement and the soft-delete behavior (deactivated, not deleted) plus the effect on historical events via recent_alerts. This adds rich context that complements the annotations without contradiction.

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

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

Three short sentences, each earning its place: the action, the ownership constraint, and the side effect. Front-loaded with the core purpose, no redundancy.

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

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

For a simple single-parameter tool, the description covers purpose, ownership, and side effects. No output schema exists, but the outcome ('cancel') is clear. Slight gap: doesn't explicitly state what happens to future alerts, though 'deactivated' implies it.

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

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

The schema already fully describes the single parameter (id with source and type). The description only implicitly references it via 'by id' and adds no new semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('cancel') and resource ('subscription') with a clear method ('by id'). It also distinguishes itself from sibling tools like subscribe and list_subscriptions, and adds unique behavioral details about ownership and soft-delete.

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

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

The description implies usage context: cancel a subscription you own, with ownership explicitly enforced. It doesn't explicitly compare to alternatives like subscribe or list_subscriptions, but the context is clear enough for an agent to know when to invoke it.

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

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

The description goes beyond annotations by explaining verdict semantics, especially the crucial distinction between could_not_verify (check didn't happen) and unsupported (no source exists). It also discloses error payload structure and the presence of verbatim evidence citations, which annotations do not cover.

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 opens with concrete query examples, then proceeds logically through routing, return values, and special cases, with no redundancy or filler.

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

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

With no output schema, the description fully covers return values (verdict list, actual values, citations, reasoning), error handling, and behavioral edge cases. It also explains the internal routing and the rationale for using the tool, making it complete for a complex tool.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The tool description does not add new parameter-level semantics beyond what the schema already provides (e.g., tolerance_pct override behavior is fully in the schema), though it does connect tolerance_pct to the 'exact percent-delta math' mentioned in the description.

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

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

The description clearly states the tool's function: natural-language claim verification with specific query patterns like 'is it true that' and 'fact check'. It distinguishes itself from siblings by detailing two distinct verification paths (SEC EDGAR for company-financial, grounded pipeline for other claims) and the specific verdicts it returns.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and gives concrete routing guidance for company-financial vs. other claims. It also notes this tool replaces 4–6 sequential calls, implying it should be used instead of chaining multiple operations.

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