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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it routes to 5,354 tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and makes one fast call. It also notes the tool handles live news, which is beyond the basic read-only hint. No contradictions found.

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

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

The description is long but information-dense. It front-loads the critical instruction ('PREFER OVER WEB SEARCH'), then provides examples and alternatives. Every sentence serves a purpose, though some redundancy exists ('START HERE', 'default entry point', 'works on every tier'). Overall, it's appropriately sized for a complex router tool.

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

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

Despite having no output schema, the description explains the return format (structured answer with citation URIs) and covers when to use, when not to use, alternatives, and edge cases. For a tool of this complexity, the description is thorough and leaves no critical gaps for an agent to mis-select or mis-invoke the tool.

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

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

Schema description coverage is 100% because all six parameters are aliases for question, each fully described in the schema. The description adds no additional parameter-specific information, only general guidance on what kinds of questions to ask. Baseline 3 is appropriate since the schema carries the semantic weight.

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: answering factual questions by routing to 5,354 tools across 1,395 sources. It uses specific verbs like 'routes', 'fills arguments', and 'returns the structured answer'. It also differentiates from sibling tools like ask_pipeworx_grounded and deep_research by describing their specialized roles.

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

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

Explicitly instructs to 'PREFER OVER WEB SEARCH' and to 'START HERE for most questions'. It provides concrete examples of query types, mentions when to step up to alternative tools ('Step up only when needed'), and even covers edge cases like breaking news. This leaves no ambiguity about when to use this tool.

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

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

Annotations already mark readOnly, openWorld, and idempotent. The description adds key behavioral context: it's a beta with candidate routing improvements enabled live, currently no active candidate so it matches stable, and it's a fully working router with no fallback. This goes beyond annotations and clarifies the experimental nature without contradiction.

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

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

Four sentences that are logically structured: definition of beta, current status, usage instruction, and clarification that it's a full router. It is concise with no filler, though slightly longer than strictly necessary due to the status explanation.

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

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

Given the simple schema (one question param), strong annotations, and reference to ask_pipeworx for response shape, the description covers all essential aspects: what it is, when to use it, current behavior, and safety. It doesn't detail response format but explicitly says it's the same as ask_pipeworx, which is sufficient 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%, with all six parameters being aliases for 'question' and fully described in the schema. The description adds no extra parameter semantics beyond confirming 'same arguments' as ask_pipeworx, which is already implied. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, an 'identical universal router' with the same 5,354 tools and response shape. It distinguishes from the stable sibling by emphasizing experimental routing improvements and notes it currently matches ask_pipeworx exactly. While it doesn't explicitly say 'ask a question,' the name and 'router' context make the purpose clear.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, implying a preference for experimental edge. It could be stronger by explicitly saying 'for stable use, use ask_pipeworx,' but the current guidance is unambiguous enough.

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 key behaviors beyond annotations: it returns {answer, evidence, confidence, source, fetched_at, refusal_reason} on success, and provides explicit refusal_reason values on failure. It also warns about the extra LLM call. These details are not present in the annotations and enrich the agent's understanding 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?

The description is dense but well-structured: it defines the purpose, explains the process, lists success/failure formats, gives usage guidance, and notes the cost trade-off. Every sentence earns its place, and the front-loaded risk framing is effective.

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

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

The description is fully self-contained for a complex tool: it covers return shape, failure modes, refusal reasons, use cases, and cost implications. The lack of an output schema is compensated by the detailed description of what the tool returns.

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 covers all parameters (100% coverage) with clear descriptions and aliases. The description does not add parameter-level detail, and per baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description opens with a precise purpose—'Hallucination-resistant answer mode for high-stakes reads'—and explains the mechanism (same routing as ask_pipeworx, then extracts answer solely from tool result). It clearly differentiates from the sibling 'ask_pipeworx' by noting the extra LLM call and preference for casual lookups.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' This tells the agent exactly when to choose this tool over the alternative, including a cost-based trade-off.

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

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

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 declare readOnly/openWorld/idempotent, but the description adds substantial behavioral detail: account/paywall requirements, not-open-web-search nature, never-invented gaps[], contradictions[], semantic excerpting, hop/citation fields, and expected latency. There is no contradiction with annotations.

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

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

The description is long but every sentence carries useful operational or behavioral information, and it is front-loaded with the account requirement and alternative to use. It loses a point because it is a dense single paragraph with some repeated concepts (e.g., citations/gaps mentioned twice), which could be tightened or 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?

Given no output schema, the description fully explains what the tool returns: findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop. It also covers prerequisites, fallback tools, timing, and edge cases for breaking news, making it complete for a complex research tool.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains depth variants (quick/standard/thorough) beyond the schema's enum text and clarifies what 'broad/multi-part' means for the question parameter. The paid-plan restriction for thorough is also mentioned.

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

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

The description states a specific, rich verb+resource: "Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources" and explains how it works (decomposes, routes to 5,354 tools in parallel, returns a findings packet). It clearly distinguishes itself from ask_pipeworx by contrasting ONE call vs single lookups and structured-data vs live-news routing.

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

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

Explicit usage guidance is front-loaded: "If you are not signed in, use ask_pipeworx instead," and later "Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx." This gives both when-to-use and when-not-to-use, naming 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 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, idempotent, and non-destructive, so the bar is lower. The description adds meaningful behavioral context: one parallel fan-out call, the data sources (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), and specific edge cases like a sunset API and fallback chains.

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

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

The description is a dense paragraph but front-loaded with user-intent examples and the core promise. Each clause adds a specific detail (sources, return fields, fallback, unsupported inputs), though splitting into shorter sentences would improve scannability.

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 and two parameters, the description fully enumerates expected output fields (cik, recent_filings with URI scheme, fundamentals, patents, news, LEI) and highlights critical constraints like zero-padded CIK and name rejection. It is complete enough for an agent to select and invoke the tool confidently, though a note on result ordering or pagination could push it higher.

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 covers both parameters with detailed descriptions and 100% coverage, including supported formats and the name-not-supported caveat. The description repeats these examples rather than adding new semantic layers, but it does reinforce the zero-padding and ticker/CIK distinction.

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: creating a full cross-source profile of a US public company, illustrated with concrete example queries. It also distinguishes itself from sibling tools by explicitly recommending this over chaining single-pack SEC/XBRL/news lookups.

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

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

The description gives explicit when-to-use guidance: whenever the user asks for a holistic view of a company. It also provides when-not-to-use by stating names are not supported and pointing to resolve_entity as the alternative, along with soft-fail behavior for patents.

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?

Annotations are all false, providing no safety hints, so the description carries the full burden. It discloses that the team reads digests daily, that signal affects roadmap, and that the tool is rate-limited to 5 per identifier per day and does not count against tool-call quota. This is valuable behavioral context beyond annotations, though it doesn't detail post-submission behavior (e.g., whether a response is returned).

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

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

The description is front-loaded with the primary purpose, then provides usage scenarios, guidance, and constraints in five concise sentences. Every sentence adds unique value (purpose, when-to-use, message guidance, team impact, rate limit/cost), with no redundancy or filler.

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

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

Given the tool's moderate complexity (3 params, nested object, no output schema), the description covers everything needed: what it does, when to use it, how to phrase the message, rate limits, and cost. It is complete 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 description coverage is 100% and each parameter is well-described in the schema. The description adds meaningful guidance for the 'message' parameter: describe the issue in terms of Pipeworx tools/packs and don't paste the end-user's prompt. This goes beyond the schema, which only says to be specific, making the description complementary.

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

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

The description starts with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes this from sibling tools by focusing on feedback rather than research or queries, and enumerates exactly what kinds of feedback (bug, feature/data_gap, praise) it accepts.

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

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

It explicitly states when to use the tool: '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 anti-guidance ('don't paste the end-user's prompt') and usage constraints (rate limit, free). This is clear and comprehensive.

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?

Annotations indicate read-only, idempotent, and non-destructive behavior, but the description goes beyond this by detailing specific response behaviors: compatibility_warning triggers, temporal_alignment semantics, skipped_cross_type counters, and the warning that most pre-mapped topics return warnings. This provides rich contextual understanding of what the tool actually does and its limitations.

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 structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence contributes meaningful information. It is front-loaded with the purpose, but the length is substantial and may be dense for an agent to parse quickly. The organization compensates, but it is not maximally 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?

Given the tool's complexity and lack of an output schema, the description fully covers the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and the meaning of skipped counters. It also addresses edge cases and limitations, making it complete for an agent to understand the tool's behavior and output.

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

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

The input schema already documents all three parameters with descriptions and examples, satisfying 100% coverage. The description adds value by explaining how the parameters interact (e.g., explicit ticker overrides topic-mapped side) and by listing the topic shortcuts. This enriches the semantic understanding beyond the schema, though the schema already carries substantial weight.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool as computing price spreads across two venues. It also differentiates from sibling tools like polymarket_arbitrage by focusing specifically on cross-venue comparison, and it elaborates on two operational modes to avoid ambiguity.

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

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

The description explicitly explains when to use each mode: topic shortcuts for quick pre-mapped comparisons and explicit ticker/slug pairing for custom events. It also warns against assuming pre-mapped topics are tradeable and describes the compatibility_warning scenarios. However, it does not explicitly mention alternative sibling tools or state 'when not to use this tool' in favor of another, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so 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 declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral detail: specific return fields (ticker, CIK, RxCUI), data sources (SEC EDGAR, RxNorm), auto-disambiguation, and internal cascading through multiple endpoints. This exceeds annotation coverage without contradiction.

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

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

The description is a single dense paragraph, but every clause earns its place: example queries, purpose, supported types, return details, and a note on efficiency. It front-loads the purpose and uses structured formatting for the types. 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?

With no output schema, the description fully compensates by detailing what each type returns (including citation URIs), accepted input formats, and internal cascade behavior. It covers inputs, outputs, and operational context, making the tool self-contained for an agent.

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

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

The input schema has 100% coverage with param descriptions, but the description enriches semantics significantly. For 'type' it enumerates supported types and their expected outputs; for 'value' it gives concrete examples per type (e.g., ticker/CIK/name for company, brand/generic for drug). This adds practical 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 the tool's function: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It uses specific verbs and resource types, provides example queries, and distinguishes itself from siblings by positioning it as the ID-lookup prerequisite.

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 instructs 'Use FIRST whenever you have a name but need an ID,' which is clear when-to-use guidance. It also notes that using this tool replaces 2-3 manual lookups, adding context on efficiency. While not naming sibling tools as alternatives, the directive is strong and unambiguous.

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavior: JS rendering, character limit, default boilerplate stripping, and supported formats. This provides context beyond the safety profile without contradicting it.

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, each providing distinct information: engine/output, default behavior, and format options. No redundancy or filler.

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

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

The description covers the tool's purpose, outputs, default behavior, and limitations (char limit) for a simple scraping operation. With no output schema, it appropriately mentions return contents. It omits error handling and API key specifics, but those are secondary.

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

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

Schema descriptions cover all 4 parameters (100% coverage). The description reiterates only_main_content's default and lists formats but does not significantly expand on schema-provided meanings. The char limit adds some context but is not parameter-specific.

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

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

Clearly states it scrapes a single URL using Firecrawl's JS-rendering engine, with specific outputs (markdown, title, description). This distinguishes it from search tools and other siblings by focusing on single-URL extraction.

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

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

Implies usage for fetching and cleaning a specific page's content. Does not explicitly mention alternatives or when not to use, but the single-URL scope is clear. There are no sibling tools that overlap directly, so explicit exclusion is unnecessary.

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?

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. Beyond that, the description adds valuable behavioral context: the dual-path routing (structured vs. grounded), tolerance_pct override behavior, verdict categories, and the output includes a pipeworx:// citation and reasoning. This goes well beyond the annotations, though it doesn't cover edge cases like rate limits or data freshness.

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 usage examples and a clear verb ('verify'). It uses punctuation to break down routing, return values, and benefits. While dense, almost every sentence adds value; only minor redundancy like listing verdicts twice could be trimmed.

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

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

Given the tool's complexity and the absence of an output schema, the description does a solid job of explaining return values (verdict, actual value, citation, reasoning) and the two operational pipelines. It covers fallback behavior and tolerance defaults. It falls short of fully describing potential error states or confidence levels, but is sufficient for an agent to know what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters by explaining tolerance_pct semantics ('Overrides the tolerance implied by the claim wording', 'set 1–2 for hallucination detection') and provides concrete examples for the claim parameter. This adds practical guidance beyond the schema's bare 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 opens with concrete natural-language triggers ('Is it true that…', 'fact check') and clearly states the tool's function: verifying factual claims against authoritative sources. It also differentiates from siblings by describing the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else) and explicitly notes it replaces 4–6 sequential calls.

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

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

The description provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and other factual claims, giving clear routing intent. However, it does not mention when not to use it or compare itself to alternative tools like search or ask_pipeworx_grounded.

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