Firecrawl

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

Beyond annotations (readOnly/openWorld/idempotent), description discloses cost implications ('you pay Anthropic directly'), default model behavior, and return structure. 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?

Three sentences front-loaded with main purpose, then default/cost, output, and use cases. No wasted words.

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

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

With no output schema, description compensates by specifying return shape (per-model {score, confidence, signals, raw_response} + combined view). Also covers default behavior, cost, and use cases, but lacks error/rate-limit details.

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

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

Schema covers 100% of parameters with descriptions. Description adds modest value by clarifying the free default and BYO key cost, but mostly restates schema info, so baseline 3 applies.

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

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

Description uses specific verb 'Probe' and states the exact resource ('LLMs about business/brand/product/topic') and output ('score visibility 0-100 per model'). It clearly differentiates from siblings by focusing on AI visibility scoring, though it doesn't explicitly name sibling alternatives.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which gives clear context. However, it doesn't mention when to prefer this over sibling tools like scan_competitor_ai_presence or compare_entities, nor any 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 indicate read-only/idempotent behavior, so the description adds useful context by disclosing that the tool routes internally, fills arguments, and returns structured answers with stable citation URIs. It doesn't cover failure modes or auth/rate-limit details, but the annotation safety profile lowers the burden.

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

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

The description is longer than average but well-structured and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). The domain list, examples, and routing advice each earn their place, though the six examples and repeated comparison to web search add mild 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 broad question-routing tool with one required parameter and no output schema, the description covers purpose, when to use it, examples, alternatives, and return format via citation URIs. However, it doesn't explicitly differentiate from close siblings like ask_pipeworx_beta or ask_pipeworx_grounded, which could matter during tool selection.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing realistic example queries ('current US unemployment rate', 'Apple's latest 10-K', 'adverse events for ozempic') and trigger phrases that help an agent formulate a valid natural-language question.

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 routing behavior: 'Routes the question to the right one of 5,767 tools across 1506 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also names concrete domains and even distinguishes itself from deep_research and web search.

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

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

It explicitly says to prefer this tool over web search for factual/current/historical data, even when web search could answer. It gives trigger phrases like 'what is', 'look up', 'get the latest', 'how much', and 'current', and names the alternative deep_research for broad/multi-part questions. It also clarifies that breaking-news queries are already handled here.

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 meaningful behavioral context beyond the annotations: it is experimental, may have routing changes enabled live, currently matches the stable router, and is a full working router with no fallback. This complements the readOnly, idempotent, and non-destructive 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 dense and front-loaded with the most important information: it is a beta, identical router with experimental routing. Each sentence contributes operational context, though there is some redundancy in saying both 'identical' and listing the same tools, arguments, and response shape.

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 beta variant with a simple question-based schema, the description covers the tool's current state, behavior, and relationship to ask_pipeworx. The lack of an output schema is partly mitigated by stating that the response shape is identical to ask_pipeworx, but the actual response structure is not described and ask_pipeworx_grounded is not addressed.

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

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

Schema coverage is 100%, with the question parameter and all aliases already documented in the schema. The description only repeats that it accepts the same arguments as ask_pipeworx, adding no new parametric meaning, 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 identifies the tool as a beta version of ask_pipeworx and a universal router over 5,767 tools, which establishes the core purpose. It distinguishes the beta from the stable sibling by mentioning candidate routing improvements, though it does not explicitly describe the end-user action (e.g., 'answers/asks') in direct terms.

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

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

The description explicitly says to use it like ask_pipeworx when you want the newest routing, and it clarifies that no candidate is active so it currently matches ask_pipeworx exactly. This provides clear situational context, though it does not list formal exclusions or mention ask_pipeworx_grounded as an alternative.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context beyond those: exact return shape, evidence as verbatim quote, refusal reasons, extraction constraints, and the extra LLM call cost. This fully communicates observable behavior in an annotated safe-read context.

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

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

The description is densely informative but well organized: lead with the core value proposition, then behavior, return format, usage guidance, and trade-off. Every sentence earns its place, and the most important decisions—groundedness and when to choose this mode—are 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?

With no output schema, the description carries the burden of explaining returns and failure modes, and it does so thoroughly: success shape, evidence field, confidence, source, fetched_at, and all refusal reasons. It also covers when to use and when not to use, 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?

Input schema coverage is 100%, and each parameter is an alias for the same question field with a complete description. The tool description adds no new parameter-level semantics, but the schema already handles parameter meaning. Baseline 3 is appropriate because the description doesn't need to compensate.

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 clear, specific purpose: a hallucination-resistant answer mode that routes through the same pipeline as ask_pipeworx but extracts answers strictly from tool results. It distinguishes itself from ask_pipeworx and ask_pipeworx_beta by emphasizing groundedness, evidence, and explicit refusals.

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 this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented. It also provides a direct alternative rule, recommending ask_pipeworx for casual lookups because this mode costs an extra LLM call. This is clear selection guidance.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing resolver behavior (market_match_confidence, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity flags, and cancellation-rule risks. These are valuable behavioral traits not visible in the schema or 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 distinct sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Every sentence provides dense, useful information without obvious redundancy, though the overall length prevents a perfect conciseness score.

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

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

Despite the absence of an output schema, the description thoroughly documents expected response shapes (result.market, result.analysis, result.evidence), the resolver contract, parent-event extraction, news fallback behavior, and status conditions. For a tool of this complexity, the description covers nearly all relevant operational and edge-case 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 description coverage is 100%, so the baseline is 3. The description reinforces parameter meanings (e.g., market accepts slug/URL/question text) and adds fan-out examples for depth, but it does not provide substantial new parameter semantics beyond what the schema already states. The examples are more illustrative of tool behavior than parameter syntax.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further explains the resolution, classification, and fan-out process, clearly distinguishing it from sibling tools like ask_pipeworx or deep_research by focusing on Polymarket bets and evidence aggregation.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context, but it does not explicitly mention when not to use the tool or name alternative tools for other scenarios, 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?

Despite annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This goes well beyond what annotations provide and fully discloses the tool's behavior.

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

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

The description is concise yet information-dense. It front-loads trigger phrases and the core function, then provides essential usage guidance and type-specific details. Every sentence earns its place, and the efficiency claim ("Replaces 8–15 sequential lookups") adds practical value. No redundancy or fluff.

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

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

For a tool with two entity types and no output schema, the description is remarkably complete. It explains the return format (paired data + citation URIs), sorting behavior, data sources, and limitations (2–5 entities). It also covers edge cases like off-calendar fiscal years. Given the complexity and lack of output schema, this is fully adequate for 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?

The schema already covers both parameters (type and values) with descriptions, so baseline is 3. The description adds meaning by explaining what each type pulls (revenue, net income, cash, debt for companies; adverse-event counts, approval counts, trial counts for drugs) and clarifying the values format (tickers/CIKs or drug names). This enriches the parameter semantics beyond schema alone.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists explicit trigger phrases ("Compare X and Y", "X vs Y", "rank these companies") and distinguishes itself from sequential single-pack lookups, 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?

It explicitly says "ALWAYS PREFER over sequential single-pack lookups when comparing entities", providing a strong when-to-use guideline. It also gives when-not-to-use by implying not to use sequential lookups, and it describes type-specific use cases (company vs drug). While it doesn't name a specific sibling tool, the guidance about avoiding sequential lookups is clear and actionable.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior; the description gives substantial additional context: account/paid-plan requirements, latency (15–90s), the full findings-packet contract (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), and guarantees like never-invented gaps and always-fetchable citations. There is no contradiction with annotations.

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

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

The definition is long and dense, but every clause carries operational information: account gate, domain boundaries, alternative routing, depth behaviors, output guarantees, and latency. It is front-loaded with the account requirement and usage conditions. The single-paragraph format hurts scanability slightly, so it falls short of a perfect 5.

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

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

There is no output schema, so the description carries the full burden of explaining what comes back. It covers the structure (findings packet, gaps[], contradictions[], hop field, citation_uri), edge behavior for unsupported topics, large-record excerpting, and latency expectations. This is unusually complete for a complex research tool.

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

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

Both parameters are already fully described in the schema (100% coverage), so the baseline is 3. The description adds consequential semantics beyond the schema: depth:'standard' triggers gap-recovery, depth:'thorough' additionally chases leads and requires a paid plan, and 'standard'/'thorough' include contradictions[]. This meaningfully helps an agent choose a depth value.

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

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

The description clearly states the tool's specific verb and resource: grounded multi-source research across Pipeworx's 1506 structured data sources in one call. It also explicitly differentiates itself from open-web search and from ask_pipeworx, 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?

The description gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete 'use ask_pipeworx instead' conditions for single lookups, breaking/current news topics, and unsigned-in users. It also explains depth-selection behavior for iterative follow-ups.

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 the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond this: it returns top-N tools with names, descriptions, and full schemas, and 'each result is ready to call directly, no second schema lookup needed.' It also states it should be called first, which is a behavioral trait. This adds context without contradicting annotations.

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

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

The description is three sentences: purpose, usage contexts, and return behavior/usage advice. Each sentence earns its place, is front-loaded with the main verb, and avoids fluff. The list of domains is compact but informative. There is no redundancy with the schema or annotations.

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 explains what the return value contains: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' It also specifies the parameter limit behavior via schema. Given the tool's simplicity and the richness of the description, it fully covers the user's need to understand when and how to use it.

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

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

Schema description coverage is 100%, so all parameters have descriptions (query, aliases, limit). The description does not add much beyond the schema, though it reinforces the natural-language nature of the query with examples like 'look up FDA drug approvals' in the schema's examples. Since the schema carries the semantic weight, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb (find), the resource (tools), and the input (description of data/task). It also distinguishes itself from sibling tools by framing itself as a meta-tool for discovering other tools, especially with the phrase 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list of domains].' It also gives a clear directive: 'Call this FIRST when you have many tools available.' This implies when not to use it (when you need one answer) and lists specific use cases, effectively distinguishing it from alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: source fan-out, soft-fail for the USPTO API sunset, empty sections as real 'no data', resolved:false for private companies, and the sources_used/sources_failed reporting. This goes far beyond the structured annotations.

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

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

Although long, the description is dense and well-structured: examples first, then purpose, then data sections, then input semantics and edge cases. Every sentence adds operational information relevant to correct invocation, and the key usage rule is front-loaded.

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

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

With no output schema, the description fully compensates by enumerating the returned fields, source behavior, URI formats, and failure semantics. It even clarifies expected outcomes for companies without certain data, making the tool's behavior predictable 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 already 100%, and the description further enriches both parameters by explaining that type values are interchangeable and value accepts ticker, zero-padded CIK, or company name. It also adds the resolution behavior and private-company notes, which the schema does not convey.

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

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

The description opens with concrete user phrasings and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call,' which is a specific verb-plus-resource statement. It also distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making selection clear.

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

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

It explicitly says to prefer this tool over chaining single-pack lookups when the user asks for a holistic view, and provides example queries that signal when it is appropriate. The description also covers edge cases like private companies and empty result sections, giving concrete expectations.

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 disclose destructive and idempotent behavior, and the description is consistent with them. It adds the context of 'previously stored memory' and 'sensitive data', but doesn't provide additional operational details beyond what annotations 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?

Two clear sentences, front-loaded with the primary action. Every sentence earns its place, and there is no redundant or tangential content.

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 destructive operation with annotations and an explicit usage guideline, the description is complete. It covers when to use, what it does, and how it relates to sibling tools, without needing to explain return values due to lack of 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?

Schema coverage is 100% for the single 'key' parameter with description 'Memory key to delete'. The description's use of 'by key' reinforces but does not add meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description begins with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from siblings 'remember' and 'recall', which are storage and retrieval operations respectively.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember and recall', providing 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?

With readOnlyHint, idempotentHint, and destructiveHint annotations already present, the description adds process detail (fetches page, extracts title/description/key links, emits markdown) and output nature (single text blob). 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 concise, front-loaded with the primary action, and structured with a useful 'Useful for' list. Every sentence adds value with no redundancy.

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

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

For a two-parameter tool with no output schema and good annotations, the description fully covers what, how, and why. It explains the output format and typical use cases, making it sufficient for an agent to decide and invoke.

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

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

The input schema already provides 100% description coverage for both parameters (url and max_links with defaults). The description doesn't add specific parameter details, so it maintains the baseline but doesn't enhance.

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 generates a production-ready llms.txt file for any URL, with specific steps (fetch, extract, emit). However, it doesn't explicitly differentiate from sibling tools like scrape or ai_visibility_check, so it falls short of full sibling distinction.

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 use cases (indexing client sites, drafting own project, auditing competitors) and describes the output format. No exclusions or alternative tool mentions are given, so it stops short of full when-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 and idempotentHint=true, so the description adds value by specifying the return fields and the include_inactive behavior. It clarifies that only active subscriptions are returned by default, enriching the behavioral context beyond the annotations.

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

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

Two sentences with front-loaded purpose and return fields. Every phrase earns its place, 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?

The tool is simple (one optional param, no output schema), and the description covers purpose, return fields, and usage context. With strong annotations and 100% schema coverage, nothing critical 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 the parameter description already fully documents include_inactive. The description adds no further parameter syntax or semantics, though it does implicitly contrast 'active' with 'cancelled', which is a minor complement. 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?

Description clearly states the verb 'List' and resource 'the caller's active subscriptions', distinguishing it from sibling tools like subscribe/unsubscribe. It also enumerates the exact fields returned, 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?

Explicitly tells when to use: 'review what you're monitoring before adding more' and 'to find an id to cancel'. This gives clear use cases and implies the tool is for inspection rather than modification, aligning with sibling 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 establish the tool as read-only, idempotent, and non-destructive. The description adds the 5,000 URL cap and the return shape {url, count, links[]}, but it does not explain what 'count' represents, link normalization behavior, or other runtime characteristics. This is adequate but not richly 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 short sentences, front-loaded with the primary action and output, and contains no extraneous detail. Every sentence contributes useful information.

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

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

Given the strong annotations and complete parameter schema, the description gives a solid overall picture. There is no output schema, and the description provides only a partial return shape; however, for a simple crawl-and-list tool, it is close to fully sufficient.

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

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

The input schema has full 100% coverage with descriptions for all four parameters, so the description does not need to add much. It restates the search relevance and URL limit, which adds no new meaning beyond the schema.

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

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

The description clearly states that the tool crawls a website and returns discovered URLs, with an optional relevance filter. This is specific enough to identify the tool's function, though it does not explicitly distinguish it from sibling tools like scrape or search_within.

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

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

Usage is implied: use this to crawl a website and get a list of URLs, optionally filtered by a search term. The description does not provide explicit when-to-use guidance or mention alternatives, but the context is clear enough for basic 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?

With no meaningful annotation hints (readOnlyHint=false, etc.), the description carries the full burden. It discloses the claim_token workflow, rate limiting ('Rate-limited to 5 per identifier per day'), account behavior, and that feedback 'doesn't count against your tool-call quota.' This is rich behavioral context beyond the annotations.

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

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

Although long, every sentence earns its place. The description is front-loaded with the core purpose, then flows through usage scenarios, exclusions, token workflow, rate limits, and cost. No filler or redundancy.

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

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

Given a 4-parameter tool with a nested context object and no output schema, the description fully covers behavior: what happens with/without an account, how to check resolution, team review cadence, rate limits, and cost implications. This is complete enough to use correctly on the first attempt.

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 explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and specifying 'with no other arguments.' This goes beyond the schema's static parameter descriptions, though most type/context meaning is already in the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on feedback submission rather than querying or 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 gives explicit when-to-use scenarios: '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 provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is model guidance with named 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?

Beyond the read-only/idempotent annotations, the description adds valuable behavioral context: it is self-aggregating, derived from a specific analytics engine, contains no PII, and is cached for 5min-1h depending on the window. This provides transparency about data provenance, privacy, and freshness that the 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 compact and well-structured: a lead sentence defining the output, a 'Useful for' list for guidance, and a final note on data characteristics and caching. Every sentence adds distinct value with no redundancy or filler, making it appropriately concise.

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 tool with one optional parameter, the description fully covers what it returns, how it sources data, privacy implications, caching behavior, and specific use cases. Without an output schema, it gives enough detail about the return content (top tools, top packs, counts) to set expectations accurately.

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 'window' parameter with an enum and explanation of trade-offs, so the description adds little new parameter-level insight. The cache note hints at a relationship to the window, but it is vague and not directly about parameter semantics. Baseline 3 is appropriate because schema coverage is 100%.

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

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

The description clearly states what the tool does: it returns top tools, top packs, and total call volume over a selected window. It distinguishes itself from siblings by focusing on aggregate trending usage rather than searching or asking questions, which is a distinct resource and purpose.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment with agent demand), which gives clear context for when to use it. However, it does not name alternatives or state when not to use this tool, so it falls short of the highest bar.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses behavioral details: it uses live CLOB depth, the Jaccard similarity threshold (≥0.30), the placeholder partition filter (>20% returns null), and the skipped_low_similarity counter. It also explains the internal arb.fill_check step and its realizable edge condition, so agents know what the tool actually computes.

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

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

The description is long but front-loaded with the main purpose and uses uppercase section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for structure. However, some details are repeated (event mode is explained twice) and the block could be tightened while preserving content.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does: opportunities[] fields, partition_check object, and the fill-check outputs. It also covers edge cases (placeholder slugs, low similarity) and trade advisory, making it effectively complete for this 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?

Although the schema already describes the two parameters, the description adds concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains the mutual exclusivity of event vs topic, and clarifies that no args triggers trending_scan. It also ties each parameter to its specific algorithm (partition_check vs cross-event comparator).

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' and immediately distinguishes the three invocation modes (trending_scan, event, topic). This clearly separates it from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

Explicit guidance is given: call with no args for trending scan, pass event for a specific market (recommended), or topic for cross-event scanning. The description also names an alternative tool, polymarket_fill_risk, for custom sizing, and warns when a signal is not tradeable (realizable_edge_pp <= 0).

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

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

Beyond the read-only/idempotent annotations, the description discloses substantial behavior: 1h KV caching keyed on knobs, the three-model family grouping, per-sport bias correction with alpha values, placeholder-slug filters, tradeable-edge gates, diagnostics so callers can see why segments are empty, and reliability caveats for Fed signals. It also reveals that partition arbs return kelly_fraction_half=0 at the parent level by design, which is critical for correct invocation.

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 well-structured with clear header-like segments in ALL CAPS (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and is front-loaded with the core purpose. Every sentence contributes useful information, though the sheer volume could be trimmed for lighter-weight scenarios.

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

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

For a complex 9-parameter tool with no output schema, the description is remarkably complete: it specifies response top-level fields (by_segment, fed_candidates/fed_note, _diagnostics), explains model families and their logic, notes caching, and clarifies why Fed bets are excluded from ranking. This gives an agent enough context to select, invoke, and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains the 'TRADEABLE-EDGE KNOBS' section, documents parameter interactions (e.g., min_kelly never filters partition_overround because parent-level half-Kelly is always 0; min_partition_leg_kelly applies per-leg instead), and provides rationale for defaults (slippage assumptions, liquidity thresholds). This goes well beyond baseline for high schema coverage.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly articulates the tool's intended use and differentiates from siblings by name-dropping specific model families (crypto_price, news_momentum, partition_overround, concentrated_longshot) and behavioral traits like 'rare-by-design' and 'filters partitions.'

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 includes an explicit use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It does not explicitly name alternatives or state when not to use it relative to sibling tools, but gives a clear context and even notes exclusions like Fed bets being surfaced but excluded from ranking.

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

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

Beyond the readOnlyHint=true annotation, the description discloses significant behavioral nuance: snapshots are only written on cache-miss, gaps mean no scan occurred, history is bounded by a 60-day TTL, and decay is computed from daily closes net of slippage, not intraday data. It also explains the difference between tracked and expired entries, giving the agent a clear model of what to expect.

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

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

Although the description is verbose, it is highly structured with labeled sections (purpose, Args, RESPONSE, LIMITS) and every sentence delivers critical operational detail. The front-loaded purpose sentence immediately establishes what the tool does, and the response field breakdown replaces the missing 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?

With no output schema, the description fully documents the response fields (tracked, expired, snapshot_dates), their semantics, and edge cases such as TTL gaps and signed edge values. It also provides competitive context ('the median lifespan is your competition clock') that helps the agent decide when this tool matters.

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 both parameters, so the baseline is 3. The description's 'Args' line mostly restates the schema ('lookback, default 14, max 30' vs schema 'clamp 2-30') and does not add substantial new meaning. The conceptual detail about snapshot families appears in both schema and description, so no extra 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 opens with a specific verb-resource pairing: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes this from sibling tools like polymarket_edges (current edge listing) and polymarket_arbitrage by focusing on the time dimension: 'how long has this edge existed and is it shrinking?'

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

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

The description states the tool's purpose in answering a specific question and explains how to interpret results (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternative tools or state when not to use it, but the contrast with current-edge tools is strongly implied through the persistence/decay framing.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate safe read-only behavior. The description goes far beyond by detailing what the tool computes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict) and warning about thin books and forced directional risk. This adds behavioral nuance annotations cannot convey.

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

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

Long but densely packed; every sentence carries distinct value. It front-loads the core purpose, then details mode-specific behavior, output fields, and concludes with a practical risk advisory. No redundant filler—the complexity justifies the length.

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

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

Despite no output schema, the description fully enumerates return fields for both modes, explains mode selection, parameter defaults, and edge-case warnings (cannot_fill, thin_legs, forced_directional_risk). The tool's operational context is thoroughly covered—nothing essential is missing.

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

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

Input schema has 100% coverage, but the description enriches every parameter: explains 'market' vs 'event' mode semantics, side defaults and auto behavior, and clarifies size_usd interpretation for single-market ('max spend on buys, target proceeds on sells') vs basket ('settlement notional S'). This transforms schema definitions into actionable operational knowledge.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to position its role as a pre-trade risk 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequence of not using it (partial basket fills convert an arb into an unhedged directional position), giving strong contextual 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?

The description goes well beyond the readOnly/idempotent annotations by disclosing key behavioral traits: pairings are keyword-matched and set pairing_unverified in either mode, spreads are gross of Kalshi's fee schedule, null temporal_alignment does not mean alignment, and unknown metric types are never paired. These details prevent misinterpretation of results and are exactly the kind of context annotations cannot convey.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence carries meaningful information about matching behavior, safety codes, or output interpretation. Some redundancy exists (e.g., the 'both modes' point is reinforced), but given the tool's complexity, the length is justified.

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

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

With no output schema, the description fully specifies the response shape: leg-by-leg prices, top_spreads_pp deltas, compatibility fields, skipped counters, and fees_note. It also explains special cases like null temporal_alignment and unclassified skipped legs, making the tool usable without any additional documentation.

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

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

Although schema coverage is 100%, the description adds relational semantics: it defines the allowed topic values, explains that explicit ticker/slug override the topic-mapped side, and states that both modes run the identical token-overlap matcher. This explains how the parameters interact, which the schema alone does not reveal.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly naming the specific resource pair and the computation. It further distinguishes itself by explaining that the delta is a real signal only when bet shapes are equivalent. This differentiates it from the Polymarket-only sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly details two invocation modes ('topic' shortcuts vs explicit ticker/slug) and warns that 'most pre-mapped topics return compatibility_warning today,' which helps an agent set expectations and decide if the tool is worth calling. It does not explicitly name sibling alternatives or state when not to use the tool, but the guidance provided is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds meaningful context beyond that, including the scoping to the user's identifier and the dual behavior of retrieving a specific value versus listing all keys based on the presence of the key argument.

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

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

The description is three sentences, each earning its place. It front-loads the core function, then provides use-case context, scoping, and tool relationships. 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?

There is no output schema, so the description bears some responsibility for return values. It implies the return of a value or list of keys, and covers scoping and pairing. However, it does not specify behavior for a missing key or the exact format of the key list, leaving a minor gap.

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

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

Schema coverage is 100% for the single key parameter, and the schema already describes 'omit to list all keys.' The description enhances this by giving examples of key content (user's target ticker, address, research notes) and reinforces the omit-to-list behavior, 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 clearly states the tool's function with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It also distinguishes itself from siblings by naming remember and forget as paired companions, and provides concrete examples of the kind of context to look up.

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

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

The description gives explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives/related tools ('Pair with remember to save, forget to delete'), covering the relationship between operations.

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 annotation readOnlyHint=true suggests the tool is read-only, but the description discloses that mark_read:true mutates state by flagging returned events as read, affecting future calls. This is a direct contradiction with the annotation. Although the description itself is transparent, the contradiction forces a score of 1 per the rubric.

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

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

The description is three sentences, front-loaded with the tool's purpose, and every sentence adds value. It covers returns, filtering, side effects, and alternatives without repetition or fluff, making it compact and well-structured.

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

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

Despite lacking an output schema, the description explains the return content (source, citation_uri, raw payload) and key behaviors (persistence, filtering, mark_read, polling). It also mentions an alternative endpoint, giving a complete picture for a simple read/filter tool in a 5-parameter context.

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

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

Schema coverage is 100%, so all parameters are described. The description adds meaning by giving an example of type ('sec_8k'), specifying since as ISO timestamp, and explaining the behavioral effect of mark_read. This goes beyond the schema descriptions, providing practical usage clarity.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), and clarifies the tool returns alerts the evaluator has written to a persisted feed. This clearly distinguishes it from siblings like list_subscriptions or recent_changes by focusing on event delivery with source and citation_uri.

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

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

The description gives clear context: filtering by type/since, using mark_read to manage state, and explicitly notes that polling works fine and provides an alternative REST endpoint for scripts/dashboards. Without naming sibling tools, it still offers usage-oriented guidance and an alternative, though it lacks explicit when-not-to-use instructions.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behavioral nuances: fan-out to multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), the specific fallback trigger (rate-limited or 5xx), and the soft-fail for USPTO due to PatentsView API sunset. It also states the return shape (structured changes[], total_changes, pipeworx:// citation URIs), which adds real transparency not available in 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 serves a purpose: query examples front-load purpose, the fan-out details explain behavior, the `since` guidance helps parameter choice, and the entity_profile alternative gives exclusion context. The use of dashes and em-dashes creates clear separation, and the length is appropriate for a tool with multiple data sources and fallback logic. No filler or redundancy.

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

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

Given the tool's complexity (three data sources, fallback logic, soft-fail, and no output schema), the description covers all essential aspects: what sources are queried, how fallback works, what inputs are accepted, what the return structure looks like, and when to use an alternative. It even mentions the 'in ONE parallel call' efficiency characteristic. This is a complete picture for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the `since` parameter with concrete examples (ISO date '2026-04-01' vs relative shorthand '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also clarifies the `value` parameter accepts ticker or CIK, which is slightly more explicit than the schema. This pushes it above baseline.

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

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

The description opens with multiple concrete query examples ('What's new with X', 'latest on Y') that make the tool's purpose unmistakable. It then states clearly: 'change feed for a company in the last N days/weeks/months in ONE parallel call,' and even distinguishes itself from sibling tool entity_profile by describing what each is for. This is a specific verb+resource description that fully differentiates from siblings.

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

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

Provides explicit when-to-use context via natural language query mappings and gives a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also offers practical parameter advice ('Use "30d" or "1m" for typical monitoring') and explains the fallback chain, so the agent understands not only when but also how the tool adapts.

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 non-read-only, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: keys are scoped by agent identifier, persistence differs between authenticated (permanent) and anonymous (24 hours), and it operates as key-value pairs. It does not detail overwrite semantics, but idempotentHint already covers repeatability.

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

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

Three sentences, front-loaded with the core purpose. Each sentence adds distinct value: what it does, when to use it, and how it relates to sibling tools. No fluff or redundancy.

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

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

For a simple two-parameter tool with no output schema, the description covers storage semantics, persistence behavior, and usage context. Combined with schema and annotations, it is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100% with descriptions for both key and value. The description goes beyond the schema by providing concrete examples of keys ('a resolved ticker, a target address') and clarifies that value accepts 'any text,' helping the agent understand expected formats and use cases.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') and resource ('data'), and distinguishes itself from sibling tools like recall and forget by framing it as the write operation in a memory workflow.

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

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

Explicit guidance is given: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives: 'Pair with recall to retrieve later, forget to delete,' making the tool's role in the ecosystem 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 indicate read-only, idempotent, non-destructive behavior, and the description adds substantial behavioral context: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit unresolved fields, source-labelled identifiers, and candidate-splitting on ambiguous matches. This far exceeds what the annotations alone convey.

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

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

The description is long but densely informative, with purpose front-loaded and parameter guidance included where relevant. Some clauses are run-on and the structure is a single sprawling paragraph, but every sentence carries meaningful guidance, so the length is largely justified.

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

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

For a complex, multi-source resolution tool with no output schema, the description explains expected return behavior: labelled identifiers, unresolved entries, figi_candidates on ambiguity, and graceful fallback. It also covers supported types, accepted input formats, and practical edge cases, leaving little ambiguity for an agent trying to call 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%, but the description goes well beyond the schema by explaining what values mean in practice: ticker, CIK, ISIN, or name for 'company'; brand or generic for 'drug'; the 'ENTITY NAME ONLY' rule; and the bond-issuer warning about trailing security-class words. This is valuable disambiguation the schema alone does not provide.

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 clear verb and resource: resolving user-spoken names to canonical/official identifiers that other tools require. It distinguishes itself from siblings like entity_profile and search by explicitly framing this as the name-to-ID gateway tool. The concrete examples of user queries ('ticker for…', 'CIK for…') make the purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', which is strong usage guidance. It also details supported types and input forms. However, it does not explicitly name sibling alternatives or state when NOT to use this tool, so it falls just short of a full 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable extra context: it probes with ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density). This goes beyond the annotations and helps the agent understand the internal mechanism and output.

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

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

The description is concise (two sentences plus a short example quote) and front-loaded with the main verb and purpose. Every sentence contributes meaning, and the quote adds relatable use-case context without padding.

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 covers purpose, internal behavior, return fields, and common use cases. It does not explain terms like 'signal density' or edge cases, but the schema and annotations fill in the remaining gaps. This is a solid, complete description 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 schema already documents all four parameters. The description adds some context (e.g., 'your brand + N competitors' clarifies the entities parameter) but does not substantially enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic). It also states the outcome: ranks by score and surfaces most/least recognized.

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 identifies a clear use case ('competitive AI-marketing audits') and provides an example question. It implicitly recommends this tool over ai_visibility_check for multi-entity comparison, but does not explicitly state exclusions or when not to use it.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds substantial behavioral context: fan-out across two services, the 5-30s first-measurement delay, and graceful degradation via 'sources_failed'. This goes beyond the annotations and fully profiles the tool's runtime 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 moderately long but every sentence carries distinct, non-redundant information: purpose, usage triggers, output structure, ecosystem scoping, and failure handling. It is well-structured with a natural flow and no filler.

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

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

Given no output schema, the description thoroughly explains the return payload (summary fields, per-advisory details, links, alternative versions), latency behavior, failure modes, and ecosystem boundaries. This is complete for a composite tool with this complexity.

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

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

Schema coverage is 100%, with both 'package' and 'version' fully described (including scoped package support and default-to-latest behavior). The description reinforces the purpose but adds no new parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a composite check for npm package adoption, naming the specific verb ('check') and resources (deps.dev, bundlephobia), and explicitly frames the use case ('should I add this npm package'). It distinguishes itself from sibling research tools by its focused npm ecosystem scope and output specifics.

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

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

The description provides explicit when-to-use guidance ('Use whenever an agent asks "is X safe / popular / small"') and scoping rules ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), effectively steering the agent away from this tool for non-npm cases. It also clarifies what to expect in terms of latency and partial failures.

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 meaningful behavioral context beyond the annotations: JS rendering, default boilerplate stripping, a 100,000-character limit, and the return of title/description. There is no contradiction with the read-only, idempotent, non-destructive annotations.

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

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

The description is front-loaded and compact: three sentences cover what the tool does, what it returns, its main default behavior, and its output options. No wasted words.

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

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

For a tool with no output schema, the description does a strong job of describing what the agent can expect: clean markdown, size limits, default main-content filtering, and selectable output formats. The schema overlays the remaining param-level details.

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

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

The schema already provides 100% parameter coverage for url, _apiKey, formats, and only_main_content. The description mostly restates schema details like formats and only_main_content rather than adding substantially new parameter-level insight.

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

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

The description clearly states the action ('Scrape a single URL'), the engine used (Firecrawl's JS-rendering engine), and the return value (clean markdown, page title, description). It clearly differentiates this tool from sibling research/search tools.

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

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

The description gives clear guidance: this is for a single URL and supports multiple output formats. It does not explicitly say when not to use it or name alternative tools, so it falls just short of full usage guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful context: return shape, default limit and max, and the fact results are ranked. This exceeds what annotations provide, though it doesn't mention rate limits or external API quirks.

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

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

Two sentences with no fluff. Purpose, input, and output are stated efficiently.

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

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

For a simple search tool, the description covers purpose, parameters, and return format. No output schema exists, but the description explicitly defines the response structure. Combined with strong annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats query and limit details already in the schema, and the _apiKey parameter is not mentioned in the description. The schema already handles parameter documentation.

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

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

Description clearly states it runs a web search via Firecrawl and returns ranked results with URL, title, and description snippet. The verb 'run' plus 'web search' specifies the action and resource, distinguishing from sibling 'search_within' which implies a different search 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?

No explicit guidance on when to use this tool vs alternatives like search_within or scrape. The description implies usage is for general web search, but there are no exclusions or references to sibling tools.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses concrete behavioral details: embedding model (BGE-base-en), retrieval window size (500-char overlapping), similarity metric (cosine), character cap (200K), and truncation behavior (truncated and flagged). These are non-obvious traits that meaningfully affect tool invocation and output interpretation.

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

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

The description is three sentences, each serving a distinct purpose: what it does, when to use it, and technical details. It is dense but not bloated; the technical sentence packs a lot of specifics while remaining readable. Slightly longer than strictly necessary, but every word contributes value.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: 'top-N passages with character offsets and similarity scores.' It also explains the search mechanism and constraints (200K cap, truncation). Combined with the clear use case and pairing guidance, the tool is fully understood from the description alone.

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

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

The schema already provides 100% description coverage for all three parameters, so the baseline is 3. The description reinforces the meaning of 'text' (fetched record), 'query' (natural-language), and 'limit' (top-N) but does not add substantial new semantics beyond the schema. The example queries are a minor enhancement, not enough to raise the 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 opens with a clear, specific verb and resource: 'Semantic search INSIDE a fetched record.' It immediately distinguishes this tool from general search (search) and other siblings by scoping it to text already pulled, and specifies the output (top-N passages with offsets and scores). This is a textbook purpose statement.

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

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

The description explicitly states when to use it: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context). It also provides an explicit alternative pairing with ask_pipeworx_grounded, telling the agent how to use it together with another tool. This is strong usage guidance.

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

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

The description adds substantial behavioral detail beyond the annotations: OAuth account requirement, phone verification, SMS daily cap, webhook auto-disable after 10 failures, and the one-time delivery.webhook_secret. These details help an agent understand side effects and constraints. 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 contributes: first sentence states purpose, then supported types, then delivery channels and caveats. It is well-organized and front-loaded, 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?

Given the tool's complexity—multiple subscription types, nested params, optional delivery channels, and no output schema—the description covers all essential aspects: how to construct each type, what delivery options exist, account requirements, and what the response includes. It is sufficiently complete for safe invocation.

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

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

Although the schema already describes all parameters, the description adds concrete, type-specific examples for the nested params object and elaborates delivery field formats and constraints. This goes beyond the schema and prevents ambiguity about how to construct valid parameters.

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

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

The description opens with a specific verb ('Create a proactive monitoring subscription') and clearly identifies the resource ('live-data event stream') and the return value (subscription id). It differentiates subscribe from siblings like list_subscriptions and unsubscribe by framing it as a creation operation.

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 rich context for when to use subscribe: it names supported subscription types, delivery channels, and account prerequisites. It does not explicitly mention listing or unsubscribing via sibling tools, but the usage context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: the return shape (category-bucketed example questions with tool+argument shapes), the live catalog source, and the optional topic parameter's effect. It doesn't contradict annotations and goes beyond the minimal safety hints.

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

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

The description is longer than average but every sentence contributes: trigger phrases, purpose, return content, parameter guidance, and when-to-use. It is front-loaded with natural language user queries. Slight redundancy in the opening question list, but not enough to penalize heavily.

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, this description fully explains what the tool returns ('category-bucketed example questions ... each with the exact tool + argument shape'), how to call it (no args vs. topic), and the onboarding context (learning meta-tools). It is complete for a simple 1-optional-param read-only tool.

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

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

Schema coverage is 100%, so the parameter is already documented. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explaining the omit-for-full-spread behavior, which is more semantic than the bare schema property list. This exceeds the baseline for high schema coverage.

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

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

The description uses a specific verb ('Returns category-bucketed example questions') and asserts a clear role: 'the onboarding entry point for an agent that just connected.' It also names the resource (Pipeworx) and differentiates from siblings by framing this as the 'first' thing to call when you don't know the system's capabilities.

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

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

Explicit when-to-use guidance is present: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It implies that other tools are for specific tasks, but it does not explicitly name alternatives or state when NOT to use this tool. This is clear context but lacks exclusion criteria.

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

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

The description discloses important behavioral traits beyond annotations: ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This complements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) 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 concise, with two sentences that convey the action, a constraint, and the outcome. Every word adds value with no redundancy.

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

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

For a single-parameter tool with clear annotations, the description is complete: it explains the action, ownership rule, effect on the row, and how historical data is preserved. No output schema is present, but the description sufficiently covers what the user needs to know.

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 'id' parameter description already states it is a subscription id returned by subscribe. The tool description merely says 'by id', adding no extra 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 the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and how it is identified (by id). It also distinguishes itself from sibling tools by mentioning deactivation (not deletion), which relates to recent_alerts.

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: you can only cancel your own subscriptions, and the row is deactivated rather than deleted. However, it does not explicitly mention when not to use this tool or point to alternatives like 'subscribe' or 'list_subscriptions'.

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 mark readOnly/openWorld/idempotent, and the description adds critical behavioral nuance beyond those: explains verdicts (confirmed, refuted, etc.), the crucial distinction between 'could_not_verify' (system failure, not evidence) and 'unsupported' (no source found), and the verbatim-evidence and citation behavior. This is exactly the kind of context agents need, and 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: example phrasings, the two-path routing, verdict list, error semantics, and a concise efficiency pitch. It opens with concrete trigger phrases that help the agent recognize when to invoke it, and the structure flows logically from purpose to behavior to return details.

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

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

With no output schema, the description fully covers return values: the six verdicts, the grounded or structured actual value with citation, and reasoning. It also explains the failure mode (could_not_verify with verification_error) and the meaning of unsupported. For a tool with multiple routing paths and edge cases, this is complete guidance.

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 explaining the purpose of tolerance_pct ('Overrides the tolerance implied by the claim wording… set 1–2 for hallucination detection') and shows how the claim parameter is interpreted via example user phrasings. This goes beyond the schema's property descriptions.

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

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

The description clearly identifies a specific verb+resource: verifying natural-language factual claims against authoritative sources. It distinguishes itself from siblings by describing its dual pipeline (SEC EDGAR fast path vs. grounded fallback) and explicitly notes it replaces 4–6 sequential calls, making its role as a specialized fact-checking tool 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 when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the internal routing (financial claims vs. any other claim), which helps set expectations. However, it does not explicitly name or exclude sibling tools like search or ask_pipeworx_grounded, so it lacks a direct comparison to alternatives.

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