Firecrawl

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

Beyond annotations (readOnly/openWorld/idempotent), description discloses cost implications ('you pay Anthropic directly'), default model behavior, and return structure. No contradiction with annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which gives clear context. However, it doesn't mention when to prefer this over sibling tools like scan_competitor_ai_presence or compare_entities, nor any exclusions.

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

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

Annotations already declare safe read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail: it routes across 5,596 tools to 1,465 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. This tells the agent what to expect in the response and how the tool operates beyond the schema.

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 quite long, but every segment earns its place. The priority directive is front-loaded, the domain list is necessary to communicate the tool's wide coverage, and the trigger phrases and examples are actionable. One point lost for redundancy in several places (the repeated parameter aliases list and the slightly repetitive tone of the trigger phrases).

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

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

Given there is no output schema, the description needs to compensate, and it does by explaining what the tool returns: a structured answer with citation URIs. It also gives a clear picture of internal routing behavior. Missing is any statement about fallback behavior, alternate if the selected tool fails, or how citations behave, but these are minor given the breadth of its stated 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 description coverage is 100%, with all six parameters documented as aliases for the single 'question' parameter. The description adds some context with natural-language examples and trigger phrases, but the schema already fully defines the semantics. Since the schema carries the semantic load, baseline 3 is appropriate; the description does not compensate for anything missing.

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 directive ('PREFER OVER WEB SEARCH') and lists the resource categories (SEC filings, FDA drug data, FRED/BLS statistics, patents, real estate, news, stocks, etc.). It clearly differentiates itself from web search and describes the tool's core function: routing a question to the right verified source and returning a structured answer with citations.

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 with trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete examples ('current US unemployment rate', 'Apple's latest 10-K'). It even states 'Use whenever... even if web search could also answer it', making the preference over the sibling alternative crystal 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses crucial behavioral context: beta status with candidate routing improvements that toggle on/off live, the current state (no candidate active as of 2026-07-26), that it matches ask_pipeworx exactly right now, and that it 'falls back to nothing' — meaning it is a complete functioning router, not a wrapper. The status-update mechanism is unusually well disclosed.

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?

Every sentence earns its place: what it is, what differs, current candidate status, usage instruction, evaluation purpose, and fallback behavior. It is dense but justified for a tool whose semantic payload is entirely about its relationship to a sibling. The most decision-relevant facts (beta, alternative usage) come first.

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 fully resolves this tool's identity and the experiment context in which it lives, including how routing decisions get validated. It names 'same response shape' via the stable sibling reference rather than describing the output, which is acceptable since the response is identical to ask_pipeworx, and no output schema exists.

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

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

Schema description coverage is 100%, so the schema fully documents the sole semantic parameter 'question' and all five aliases. The description references 'same arguments' but adds no parameter-level detail; with complete schema coverage, baseline 3 is appropriate.

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

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

The description states a specific function: a universal router that is the beta variant of ask_pipeworx, with the same 5,596 tools, arguments, and response shape. It actively differentiates itself from its sibling ask_pipeworx (stable) by framing itself as 'the experimental edge' while confirming it is a full working router.

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

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

The description gives explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router to decide merges. It names the sibling alternative and the condition that selects this tool, though it does not explicitly state when NOT to use it (e.g., when stability is preferred).

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 signal read-only, idempotent, non-destructive behavior, but the description goes further by defining refusal behavior, the guarantee of using 'ONLY what the tool result contains', and the refusal_reason enum values. It adds strong context about fallback and failure modes that annotations could not express. No contradiction with the annotations.

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

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

The description is dense and front-loaded, opening with the key identity: 'Hallucination-resistant answer mode for high-stakes reads.' It consumes several sentences for output shape, refusal reasons, use context, and cost tradeoff. Slightly long, but every sentence carries useful operational information and it is efficiently 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?

Without an output schema, the description compensates robustly by specifying the return object {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and all five refusal_reason possibilities with trigger conditions. It covers the high-stakes use case, the casual-alternative tradeoff, and the safety behavior, making complete invocation context available to the agent.

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

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

Schema description coverage is 100%, and the schema already explains the one meaningful parameter, a natural-language question with aliases for query, q, prompt, text, input. The tool description does not deepen parameter semantics or give examples, but the baseline is fine because the schema fully handles parameter meaning.

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

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

States a specific action and mode: 'hallucination-resistant answer mode' for the 'ask_pipeworx' resource, and distinguishes it from sibling tools like ask_pipeworx by name: 'same routing as ask_pipeworx' but returns grounded evidence or an explicit refusal. The description clearly signals what this tool does and how it differs from the related sibling.

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 identifies when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names an alternative, asks the agent to 'prefer ask_pipeworx for casual lookups', and notes the cost tradeoff of one extra LLM call. This is a complete when-and-when-not guidance.

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

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

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?

With readOnlyHint=true, openWorldHope=true, idempotentHint=true already provided, the description still adds significant non-annotation context: paid-plan gating for 'thorough' depth, decomposition into facets, explicit gaps[] and 'never invented' guard, contradiction detection, citation_uri resolvability guarantee, semantic (not head-truncated) excerpting, and run-time expectations. No contradiction with the read-only/idempotent annotations exists.

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

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

The description is information-dense and uses front-loading: account/tier blocker first, then core function, then usage routes, then behaviors. However, it runs to roughly 250 words in a single block with heavy technical differentiation that must be fully parsed; sentences that are genuinely valuable, yet density edge still makes it hard to skim quickly.

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

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

For a complex tool with no output schema, the description explicitly covers the returned findings packet (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] failure mode, contradiction output, latency budget (15-90s), and when to expect empty results. An agent has everything needed to invoke the tool and interpret what comes back.

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

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

Input schema coverage is 100% with clear per-parameter descriptions, so the heat-baseline is 3. The description adds meaningful beyond-schema value for depth—the paid requirement for 'thorough', hop-count semantics, gap-recovery differences between 'standard'/'thorough'—and reinforces the question parameter with 'decomposition is the point'.

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

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

The description names a specific verb and resource: 'Decomposes your question into focused facets, routes each to the right one of 5,596 tools IN PARALLEL' across '1465 STRUCTURED data sources' — far more specific than the title. It differentiates from siblings by explicitly clarifying that this is 'NOT open-web research' and distinguishing from ask_pipeworx. An agent can tell exactly what this tool does and what it is not.

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 documents when to use this tool versus alternatives: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead', 'If you are not signed in use ask_pipeworx instead', and 'prefer ask_pipeworx' for breaking/colloquial news. This coverage is thorough 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 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?

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and specifying 'with no other arguments.' This goes beyond the schema's static parameter descriptions, though most type/context meaning is already in the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools (e.g., ask_pipeworx, discover_tools) by focusing on feedback submission rather than querying or discovery.

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

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

The description gives explicit when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is model guidance with named alternatives.

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

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

Beyond the read-only/idempotent annotations, the description adds valuable behavioral context: it is self-aggregating, derived from a specific analytics engine, contains no PII, and is cached for 5min-1h depending on the window. This provides transparency about data provenance, privacy, and freshness that the annotations do not cover.

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

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

The description is compact and well-structured: a lead sentence defining the output, a 'Useful for' list for guidance, and a final note on data characteristics and caching. Every sentence adds distinct value with no redundancy or filler, making it appropriately concise.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' and immediately distinguishes the three invocation modes (trending_scan, event, topic). This clearly separates it from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

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

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

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

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

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

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

The description is long and dense, but it is well-structured with clear header-like segments in ALL CAPS (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and is front-loaded with the core purpose. Every sentence contributes useful information, though the sheer volume could be trimmed for lighter-weight scenarios.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% with clear descriptions for both parameters, so the baseline is 3. The description's 'Args' line mostly restates the schema ('lookback, default 14, max 30' vs schema 'clamp 2-30') and does not add substantial new meaning. The conceptual detail about snapshot families appears in both schema and description, so no extra value beyond the schema.

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

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

The description opens with a specific verb-resource pairing: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes this from sibling tools like polymarket_edges (current edge listing) and polymarket_arbitrage by focusing on the time dimension: 'how long has this edge existed and is it shrinking?'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to position its role as a pre-trade risk check.

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

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

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

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

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

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, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds significant context: it cascades through multiple lookups, degrades gracefully when external APIs fail, resolves ISINs to legal entities, and explicitly states unresolved identifiers are listed under 'unresolved'. However, it doesn't mention rate limits or potential latency, which would push to 5.

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 front-loaded with example query patterns, making it easy for an agent to match user intent. It uses clear headings like 'SUPPORTED TYPES' and lists identifiers with sources. However, it could be slightly more concise by removing the parenthetical on LEI enrichment that repeats the structure of the preceding list.

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 2 parameters, 100% schema coverage, no output schema, and rich annotations, the description covers the key behavioral aspects: multi-source resolution, graceful degradation, explicit unresolved identifiers. It doesn't detail return format or pagination, but given the tool's complexity and no output schema, the description is sufficiently complete for an agent to use it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by specifying that ISINs like 'CH0038863350' resolve to legal entities, and that LEI/FIGI enrichment degrades gracefully. It also clarifies that for 'drug' type, it returns RxCUI, ingredient, and brand, which is not in the schema. This lifts it to a 4.

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

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

The description is highly specific, listing multiple query patterns ('What's the ticker for…', 'find the CIK for…') and explicitly stating the tool resolves names to official identifiers. It distinguishes itself from siblings like 'compare_entities' or 'entity_profile' by focusing on name-to-ID resolution, which is a unique 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 explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also includes when-not-to-use implicit differentiation (replaces 2-3 manual lookups) and mentions graceful degradation for LEI/FIGI, making it clear this is the primary tool for entity resolution among siblings.

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

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

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

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

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

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

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

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

For a tool with no output schema, the description covers purpose, internal behavior, return fields, and common use cases. It does not explain terms like 'signal density' or edge cases, but the schema and annotations fill in the remaining gaps. This is a solid, complete description for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds some context (e.g., 'your brand + N competitors' clarifies the entities parameter) but does not substantially enhance parameter understanding beyond the schema.

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

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

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

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

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

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

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds substantial behavioral context: fan-out across two services, the 5-30s first-measurement delay, and graceful degradation via 'sources_failed'. This goes beyond the annotations and fully profiles the tool's runtime behavior.

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

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

The description is moderately long but every sentence carries distinct, non-redundant information: purpose, usage triggers, output structure, ecosystem scoping, and failure handling. It is well-structured with a natural flow and no filler.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Description clearly states it runs a web search via Firecrawl and returns ranked results with URL, title, and description snippet. The verb 'run' plus 'web search' specifies the action and resource, distinguishing from sibling 'search_within' which implies a different search scope.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The schema already provides 100% description coverage for all three parameters, so the baseline is 3. The description reinforces the meaning of 'text' (fetched record), 'query' (natural-language), and 'limit' (top-N) but does not add substantial new semantics beyond the schema. The example queries are a minor enhancement, not enough to raise the score.

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

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

The description opens with a clear, specific verb and resource: 'Semantic search INSIDE a fetched record.' It immediately distinguishes this tool from general search (search) and other siblings by scoping it to text already pulled, and specifies the output (top-N passages with offsets and scores). This is a textbook purpose statement.

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

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

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

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

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

The description adds substantial behavioral detail beyond the annotations: OAuth account requirement, phone verification, SMS daily cap, webhook auto-disable after 10 failures, and the one-time delivery.webhook_secret. These details help an agent understand side effects and constraints. No contradiction with annotations.

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

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

The description is dense but every sentence contributes: first sentence states purpose, then supported types, then delivery channels and caveats. It is well-organized and front-loaded, with no filler or repetition.

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

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

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

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

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

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

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

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

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

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

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

The description provides rich context for when to use subscribe: it names supported subscription types, delivery channels, and account prerequisites. It does not explicitly mention listing or unsubscribing via sibling tools, but the usage context is clear and actionable.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description discloses important behavioral traits beyond annotations: ownership enforcement, deactivation instead of deletion, and that historical events remain accessible via recent_alerts. This complements the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) without contradicting them.

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

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

The description is concise, with two sentences that convey the action, a constraint, and the outcome. Every word adds value with no redundancy.

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

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

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

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

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

Schema coverage is 100% and the 'id' parameter description already states it is a subscription id returned by subscribe. The tool description merely says 'by id', adding no extra semantics beyond the schema.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and how it is identified (by id). It also distinguishes itself from sibling tools by mentioning deactivation (not deletion), which relates to recent_alerts.

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

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

The description provides clear context: you can only cancel your own subscriptions, and the row is deactivated rather than deleted. However, it does not explicitly mention when not to use this tool or point to alternatives like 'subscribe' or 'list_subscriptions'.

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

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

The annotations already mark readOnly/openWorld/idempotent, and the description adds critical behavioral nuance beyond those: explains verdicts (confirmed, refuted, etc.), the crucial distinction between 'could_not_verify' (system failure, not evidence) and 'unsupported' (no source found), and the verbatim-evidence and citation behavior. This is exactly the kind of context agents need, and no contradiction with annotations.

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

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

The description is dense but every sentence earns its place: example phrasings, the two-path routing, verdict list, error semantics, and a concise efficiency pitch. It opens with concrete trigger phrases that help the agent recognize when to invoke it, and the structure flows logically from purpose to behavior to return details.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of tolerance_pct ('Overrides the tolerance implied by the claim wording… set 1–2 for hallucination detection') and shows how the claim parameter is interpreted via example user phrasings. This goes beyond the schema's property descriptions.

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

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

The description clearly identifies a specific verb+resource: verifying natural-language factual claims against authoritative sources. It distinguishes itself from siblings by describing its dual pipeline (SEC EDGAR fast path vs. grounded fallback) and explicitly notes it replaces 4–6 sequential calls, making its role as a specialized fact-checking tool unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the internal routing (financial claims vs. any other claim), which helps set expectations. However, it does not explicitly name or exclude sibling tools like search or ask_pipeworx_grounded, so it lacks a direct comparison to alternatives.

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