recipes

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 context: default model is Workers AI Llama-3.3-70b (free), `_apiKey` enables Anthropic probing with direct payment to Anthropic, and the return format includes per-model `{score, confidence, signals, raw_response}` plus a combined view. This exceeds what annotations specify 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?

Three sentences, each earning its place: the first states the core action and output, the second explains model defaults and API key handling, the third lists use cases. Front-loaded and free of 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?

With no output schema, the description carries the full burden of explaining return values, which it does explicitly (per-model structure plus combined view). It also covers model selection, key handling, and use cases, making the tool's behavior sufficiently clear for an agent to invoke correctly.

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

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

The schema already documents all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds semantic nuance by explaining the cost/free default for the `models` parameter and the BYO-key nature of `_apiKey`, clarifying trade-offs not 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 uses a specific verb ('Probe') and resource ('one or more LLMs') to define the action, and clearly states the output (visibility score 0-100 per model). It distinguishes from siblings by focusing on AI visibility scoring for brands/topics, making the tool's purpose unmistakable.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context for when to use it. However, it does not mention alternatives or exclusions relative to sibling tools like `scan_competitor_ai_presence` or `ask_pipeworx`, so it stops 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it routes to a vast tool network, fills arguments, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. It also clarifies the news-routing behavior. No contradiction with annotations.

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

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

The description is long but highly structured and front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'). Every sentence earns its place: domain list, routing behavior, trigger phrases, examples, alternatives, and news coverage. There is no fluff or repetition of schema 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 explains the return value ('structured answer with stable pipeworx:// citation URIs'). It also covers supported question types, default usage, alternatives, tier availability, and speed. The tool's complexity is high, but the description addresses all key contextual aspects an agent needs to select and invoke it correctly.

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

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

Schema coverage is 100%, with all six params being aliases of 'question' and clearly described. The description enriches the parameter meaning by providing a wide range of example questions ('current US unemployment rate', 'Apple's latest 10-K') and trigger phrases ('what is', 'look up', 'find'), which helps agents formulate valid queries beyond the schema's minimal description.

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

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

The description states a specific verb+resource: it 'routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' with concrete trigger phrases. It also specifies when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research', covering exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it is a full working router ('Falls back to nothing'), it may have candidate routing improvements enabled live, and it currently matches ask_pipeworx exactly because no candidate is active. This directly addresses what the agent should expect regarding experimental 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 four sentences, front-loaded with the beta identity and key constraints. Each sentence provides distinct information: current state, usage, and experimental nature. It is slightly long but the nuance of a beta router with a possible active candidate 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?

The description covers identity, current behavior, usage, and stability for an experimental router. It mentions the same response shape and that it is fully functional, which is important since there is no output schema. It does not explain the difference from ask_pipeworx_grounded, but that is not essential for using this tool.

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

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

The schema has 100% coverage for all six parameters, each documented as an alias for 'question'. The description does not add parameter-specific details beyond noting 'same arguments' as ask_pipeworx. Since the schema already explains everything, the baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself by being the experimental edge with candidate routing improvements, and it explicitly names the stable counterpart (ask_pipeworx). This goes beyond a simple restatement and provides specific scope.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also informs the user that no candidate is active currently, so it matches ask_pipeworx exactly. This gives clear context for when to use it, though it does not explicitly recommend the stable tool for non-experimental use.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool makes an extra LLM call, returns evidence verbatim quotes, and produces explicit refusal_reason codes. This enriches the agent's understanding of runtime behavior, including failure modes.

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

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

The description is compact yet packed with essential information: purpose, mechanism, success/refusal return shapes, usage scenarios, and cost trade-off. Each sentence contributes value, and the structure is logical and front-loaded.

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

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

No output schema exists, but the description compensates by detailing both success and refusal response structures, enumerating refusal reasons, and explaining the cost differential relative to the sibling tool. This makes the tool's behavior fully understandable in 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?

Input schema has 100% coverage with all parameters as aliases for 'question', each described. The description adds no additional parameter semantics, but the schema is sufficient. Baseline 3 applies since the schema handles the heavy lifting.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx. It specifies the mechanism (picks tools, fetches data, extracts answer only from results) and explicitly differentiates from the sibling tool by highlighting the extra LLM call and refusal behavior.

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

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

Explicit guidance is provided: use when answers will be quoted, cited, or acted on, and must not invent facts. It also contrasts with ask_pipeworx for casual lookups, giving clear when-to-use vs. 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavior beyond that: resolver contract (match confidence, alternatives, suggestions), parent-event extraction, safety short-circuiting for low-confidence matches, closed-market status, wide-spread illiquidity flags, cancellation-rule parsing, and response shapes. It also discloses news fallback fields and failure modes, giving agents a clear picture of edge-case 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 a very long paragraph that uses ALL-CAPS section labels (RESOLVER CONTRACT, SAFETY, etc.) to improve structure and front-loads purpose and usage. However, it is dense and verbose, with many sub-clauses, making it hard to scan quickly. It is not concise, though every section does add important context.

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

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

With no output schema, the description fully specifies result structure: result.market fields, result.analysis, result.evidence, resolver match fields, parent_event, news fallback fields, and status strings. It also covers edge cases like low-confidence short-circuits, closed markets, wide spreads, and cancellation-rule risk, making it complete for an agent to invoke correctly.

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

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

The input schema has 100% coverage and already provides descriptions for all three parameters (market formats, depth enum, include_raw defaults). The description repeats some of this but adds no materially new parameter semantics, so the 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 opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', clearly identifying the verb (research), resource (Polymarket bet), and mechanism. It explicitly lists intended use cases ('Use for "should I bet on X"...') and distinguishes this tool from sibling Polymarket tools focused on arbitrage or 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?

Provides explicit context with 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives concrete fan-out examples for different bet types. However, it doesn't explicitly mention when NOT to use this tool or name alternative siblings like polymarket_arbitrage, so it lacks exclusionary guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), specific financial metrics, correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This far exceeds the annotation baseline.

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

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

The description is long but well-structured: trigger phrases, core purpose, type-specific details, sorting, and output format. There is minor redundancy between 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups,' but overall every sentence adds value for a complex tool.

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

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

For a tool with no output schema, the description covers what data is pulled, how results are sorted, and that citations are returned. It could explicitly mention response units or exact formatting, but the provided detail is sufficient for an agent to know what to expect and how to invoke it correctly.

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

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

With 100% schema coverage the baseline is 3, but the description adds critical meaning beyond the schema: it maps type=company to specific metrics (revenue, net income, cash, long-term debt) and type=drug to adverse-event/approval/trial counts, and explains fiscal-year handling that affects values. This gives agents a much richer understanding of parameter behavior.

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

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

The description opens with natural-language trigger phrases and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It goes beyond a generic 'compare' verb by specifying the resource types (companies/drugs) and the parallel execution model, distinguishing it from sibling tools like entity_profile.

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 the tool via query examples ('X vs Y', 'which is bigger', 'rank these companies') and gives an explicit directive to prefer it over sequential lookups. It also clarifies the 2–5 entity limit and type-specific use cases (company financials vs drug trial/adverse-event data).

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

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

Annotations already declare safety (readOnly, idempotent, openWorld). The description adds substantial context: account requirements, response packet composition (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), the gaps[] contract, contradictions[] for standard/thorough, hop fields, citation_uri fetchability guarantee, semantics excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is long but dense with critical operational details that aren't available elsewhere. Each sentence adds value, though it is a single massive paragraph that could benefit from bullet points or section breaks. It front-loads the account requirement and immediate fallback, which is pragmatically useful.

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 parameters and no output schema, the description is remarkably complete: it explains the execution model, return structure, failure modes (gaps when not in catalog), alternative suggestion, timing, and citation semantics. The agent is well-equipped 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 covers 100% of parameters, but the description enriches meaning significantly: it explains the behavioral differences between depth levels ('quick=3', 'standard=5... adds a gap-recovery hop', 'thorough=8... chases leads'), and clarifies that question decomposition is the point. This goes well beyond the schema's enum 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 states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and clearly differentiates from siblings by contrasting with ask_pipeworx ('For a single lookup use ask_pipeworx'). It explains the one-call parallel decomposition process, making the purpose distinct and unambiguous.

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

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

Explicitly provides when-to-use: 'Best for broad/multi-part questions over structured data' and when-not-to: for breaking/current news 'prefer ask_pipeworx' because deep_research returns empty gaps. It names the alternative tool (ask_pipeworx) and addresses account tiers, giving the agent clear decision 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful return-value context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations and helps set expectations.

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

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

The description is three sentences, each earning its place: first states the core purpose, second details supported domains, third explains the return format and usage guidance. No redundant or fluff 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?

Since there is no output schema, the description adequately explains return values (names, descriptions, schemas, examples). It also clarifies when to use the tool and what to expect. For a read-only discovery tool, this is complete. The domain list adds useful 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 well-documented in the schema. The description reinforces query usage with examples and mentions aliases, but it doesn't add parameter-level detail beyond what the schema already provides. 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 verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes itself as a meta-tool for discovering other tools, reinforced by the detailed list of domains. This differentiates it from siblings like search_within or search_meals.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not name specific alternatives, but the 'call first' advice guides the agent toward the intended workflow.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior beyond annotations: it explains the parallel fan-out across sources, the USPTO API sunset with soft-fail behavior, the GDELT→GNews fallback, and the exact structure of returned data (e.g., sorted fundamentals, URIs for filings). No contradictions with annotations.

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

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

The description is a single dense paragraph but is well-structured: examples are front-loaded, followed by usage guidance, a list of return fields, and input format constraints. Every sentence adds information. It is longer than ideal but justified by the tool's complexity and lack of an output schema.

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

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

With no output schema, the description fully explains return values: CIK, company name, recent filings with URIs, fundamentals (latest 10-K revenues, net income, cash), patents with the API sunset note, news fallback, and LEI. It also covers input constraints and edge cases (name unsupported, soft-fail), making the tool understandable without further documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning with concrete examples ("AAPL", "0000320193") and reinforces the constraint that names are not supported. It also clarifies that type is currently limited to 'company'. While the schema already covers the core semantics, the examples and additional context push it slightly 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 clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and lists the exact outputs (CIK, filings, fundamentals, patents, news, LEI). It also distinguishes itself from siblings by explicitly advising to prefer it over chaining single-pack lookups and mentioning resolve_entity for name inputs.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This is strong usage guidance with an alternative tool named.

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 (destructiveHint: true) and idempotent (idempotentHint: true) behavior, lowering the bar. The description adds 'clear sensitive data' as a use case but no additional behavioral detail such as irreversibility or behavior on missing keys. It does not contradict annotations.

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

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

The description is compact and front-loaded with the core action in the first sentence. Subsequent sentences provide usage guidance and related tools without redundancy, earning every word's place.

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

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

For a single-parameter deletion tool with strong annotations, the description covers purpose, usage, and complementary tools. It omits specifics about return values or missing-key behavior, but these are not critical given the tool's simplicity and the idempotent/destructive hints.

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% coverage for the 'key' parameter with 'Memory key to delete'. The description adds slight context ('previously stored', 'by key') but does not materially enhance the parameter semantics beyond what the schema documents.

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: 'Delete a previously stored memory by key.' This is a specific verb+resource pair that fully distinguishes it from sibling tools like remember and recall, which are explicitly referenced as paired tools.

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

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

The description provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also names complementary tools ('Pair with remember and recall'), effectively guiding the agent on when and how to use this tool relative to 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 annotations (readOnly, idempotent, openWorld), the description discloses the operational flow: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies the output is a single blob ready for a specific location. This adds meaningful behavioral 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?

Three sentences cover purpose, process, and use cases with zero redundancy. Information is front-loaded—the core action appears in the first sentence. Every element earns its place.

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

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

The tool is simple (2 params, no output schema), and the description sufficiently explains what is returned (a standard llms.txt text blob) and how it is produced. It also gives practical contexts, making it complete for an agent to act confidently.

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

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

Schema coverage is 100% and both parameters (url, max_links) are well-described in the schema. The description adds no supplementary parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It also outlines the process (fetch, extract, emit) and differentiates from likely siblings by mentioning competitor auditing. This is a model of purpose clarity.

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 'Useful for:' scenarios—client indexing, personal projects, and competitor auditing—giving clear when-to-use guidance. However, it does not name specific alternative tools or state when not to use, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds no further behavioral caveats (e.g., errors, rate limits) but also doesn't contradict annotations. It adds minimal extra context beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core action, and contains no filler. Every sentence earns its place, covering what it returns and how to construct the call.

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 simplicity (single required parameter), the existing output schema, and comprehensive annotations, the description is sufficiently complete. It tells the agent what the tool does, what the output includes, and where to source the ID, covering all necessary selection and invocation 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?

The schema already documents the 'id' parameter with examples and description (100% coverage), so the baseline is 3. The description adds valuable semantic context by telling the agent where to obtain valid IDs ('from search_meals or random_meal'), which helps ensure correct invocation.

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 'Get complete recipe details' with specific content (ingredients, measurements, step-by-step instructions). It distinguishes from siblings like search_meals (which lists meals) and random_meal (which returns a random meal) by specifying this tool retrieves full details for a given ID.

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

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

The description explicitly says 'Pass a meal ID from search_meals or random_meal', giving a clear workflow for when to use this tool. It doesn't explicitly mention alternatives to avoid, but the context makes it obvious this is the detail-fetching step after obtaining an ID.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds behavioral context that the tool scopes results to the caller ('caller's active subscriptions') and lists the return fields, which annotations don't provide. It doesn't mention default filtering to active only, but that's partially addressed by the schema parameter.

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: first states the purpose and returned fields, second gives usage guidance. No fluff, essential information only, and the most important facts are front-loaded.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description sufficiently covers purpose, return fields, and typical usage scenarios. It is complete for an agent to decide when to use the tool and what to expect.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the schema fully documents it. The description does not add any additional parameter semantics, which is acceptable given the baseline of 3 when schema covers params fully.

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 lists the caller's active subscriptions, and enumerates the exact fields returned. This specific verb+resource combination distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies when to use it relative to subscribe/unsubscribe, though it doesn't explicitly state when not to use it or name alternative tools. Still, the 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, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds behavioral context by stating it returns 'all recipes' and specifies the output format (meal names and IDs), which is useful beyond the annotations.

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

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

The description is concise, consisting of two sentences that immediately state the action and key details. It is well-structured and free of unnecessary 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?

The tool is simple (one parameter), has comprehensive annotations, and includes an output schema. The description fully covers the tool's purpose, examples, and downstream usage, so nothing is missing for this low-complexity tool.

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

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

The input schema already fully describes the only parameter with 100% coverage. The description adds examples but no additional semantic depth beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Find' with a clear resource and scope: 'all recipes using a specific ingredient'. It also provides examples and mentions returning meal names and IDs, which distinguishes it from siblings like random_meal (random selection) and search_meals (likely keyword search).

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

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

The description clearly implies when to use this tool (when filtering recipes by ingredient) and provides a workflow hint by stating the results are 'to pass to get_meal'. However, it does not explicitly exclude alternatives or name sibling tools for different use cases.

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

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

Annotations are all false and provide no behavioral hints, so the description carries the full burden. It discloses the claim_token flow (filing without an account returns a token, passing it back later to read status), rate limiting ('5 per identifier per day'), that feedback is free, and that it doesn't count against tool-call quota. No annotation contradiction 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?

Although long, every sentence earns its place: it covers purpose, use cases, exclusions, claim token mechanics, rate limits, cost, and roadmap impact. The content is front-loaded with the core purpose first, and no redundant filler is present.

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 4 optional parameters, one enum with 5 values, a nested object, and no output schema, the description covers all necessary context: when to use, what happens on filing, how to retrieve status, rate limits, and the boundary of scope (Pipeworx-only). The absence of an output schema is mitigated by describing the claim_token response behavior.

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 all parameters with descriptions (100% coverage), so baseline is 3. The description adds significant value by explaining the claim_token usage flow and mapping the type field categories to concrete use cases (bug, feature, data_gap, praise). This lifts it above the baseline.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's purpose as a feedback channel, distinct from all sibling tools like ask_pipeworx or discover_tools. The scope is further clarified by explicitly limiting it to tools served by this Pipeworx connection.

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: bug (wrong/stale data), feature/data_gap (wish a tool existed), and praise. It also gives a clear exclusion: if the tool came from a different MCP server, file with that server instead. This is textbook usage differentiation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This goes beyond annotations and provides meaningful operational details.

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

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

The description is well-structured: a hook sentence, a factual statement of returns, a bulleted list of use cases, and a concise technical note on caching and privacy. Every sentence adds value, and it is front-loaded with the core functionality.

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 simplicity (one optional parameter, no nested objects) and rich annotations, the description is complete. It covers the return payload, use cases, caching behavior, and privacy characteristics, leaving no critical gaps for an agent to invoke it correctly.

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

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

The only parameter 'window' is fully described in the schema (100% coverage) including the default, enum values, and the interpretation of shorter vs longer windows. The description merely repeats the same information, so it adds no additional meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'Returns' and resource specificity distinguish it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit 'Useful for' scenarios with three numbered use cases, giving clear context on when to use the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds deep behavioral context: the semantic anchor (≥0.30 Jaccard similarity), partition placeholder filter (>20% placeholder fraction returns null), and the CLOB depth fill check with the warning 'do not trade it'. No contradictions 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 long (roughly 250 words) yet well-structured with labeled blocks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear front-loaded purpose statement. It earns a 4 instead of a 5 because the density is high, but every sentence contributes meaningful detail.

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

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

With no output schema, the description fully specifies the return shape: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases and the fill-check sub-result, leaving no critical information to guess.

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, but the description enriches them with examples (fed-decision-may-2026), mode-specific behaviors (walks child markets, checks date/threshold-axis ordering), and output fields. It goes far beyond the schema's brief descriptions.

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

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

The description opens with a specific purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from sibling polymarket_fill_risk by naming it for custom sizing, and the two modes ('event' and 'topic') make the scope concrete.

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 for when to call with no args, with an 'event' slug, or with a 'topic' seed question. It also directs users to polymarket_fill_risk for custom sizing and warns against trading when realizable_edge_pp ≤ 0, providing both positive and negative usage conditions.

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 readOnly/idempotent annotations by disclosing caching behavior (Cached 1h at the KV level), diagnostics for empty segments, placeholder-slug filters, the rationale for excluding Fed bets, and the fact that partition arbs return kelly_fraction_half=0 at parent level. This is exceptionally 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 extremely long and dense, with detailed formulas, per-sport α values, and specific gate relaxation histories. Although well-structured with sections and front-loaded purpose, it is not concise and includes details beyond what an agent likely needs for tool selection and invocation.

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?

Even with no output schema, the description comprehensively documents the response structure (by_segment, fed_candidates, _diagnostics), explains why segments may be empty, lists per-opportunity fields, and describes caching. It is complete for a tool of this complexity.

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

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

Schema descriptions cover all 9 parameters (100%), but the description adds meaningful context: the TRADEABLE-EDGE KNOBS section explains how min_liquidity, max_spread_pp, and min_partition_leg_kelly affect results, and it clarifies that slippage_pp is subtracted from raw edge. This adds value beyond the schema alone.

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

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

The description clearly states that the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It also outlines three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making it distinct from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 says it is 'Built for "what should I bet on today"', which clearly conveys the intended use case. It also explains when to adjust tradeable-edge knobs and why Fed bets are excluded, but it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: snapshots are written on cache-miss, gaps mean no scan occurred, history is bounded by a 60-day TTL, and decay uses daily closes not intraday. This goes far beyond the annotations and provides a clear operational model.

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

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

The description is longer than average but well-organized with uppercase section markers (Args, RESPONSE, LIMITS). It front-loads the purpose statement and each sentence contributes operational detail. It could be trimmed slightly, but the structure makes the information scannable and worth its 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?

With no output schema, the description fully specifies the response shape (tracked[], expired[], snapshot_dates[]), explains what each field means (including trend enum and decay_pp_per_day), and covers limitations (TTL, cache-miss gaps, daily-close basis). This is complete for a tool of this complexity, and annotations cover the safety profile.

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%: both 'days' and 'window' have explicit descriptions in the input schema. The description's Args section only restates defaults already present in the schema (e.g., 'default 14', 'default 1wk') and adds the phrase 'snapshot family' which is also present in the schema. It adds no meaningful new parameter semantics beyond what is already structured.

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 as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and phrases the core question it answers: 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges, which likely returns current edges, by emphasizing historical tracking and decay analysis.

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

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

The description provides a clear context for when to use the tool ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying it is for assessing edge persistence over time. However, it does not explicitly name alternative tools or state when NOT to use it, so it stops short of full exclusionary guidance.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral detail: it 'walks the ladder', returns specific metrics, and discloses risk implications like 'thin_legs' and 'forced_directional_risk' that could strand the user. This goes far 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 long but front-loaded with a crisp one-sentence summary. It is structured with clear mode labels (SINGLE-MARKET, BASKET) and lists output fields. A few unnecessary capitalizations and dense phrasing detract slightly, but every sentence adds value and the structure aids scanning.

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 enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, profit_usd, thin_legs). It also covers edge cases like defaults, clamps, and the risk of partial fills, making it fully contextually complete for a complex tool.

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

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

The input schema has 100% coverage, but the description enriches the parameters further: it explains that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, with default and clamp values. It also clarifies that `market` and `event` are mutually exclusive modes, which is not explicit 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' which clearly states the verb (check) and resource (fill risk against order book depth). It distinguishes itself from sibling tools by explicitly naming when to use it ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), setting it apart from arbitrage and edge detection tools.

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

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

The description provides explicit usage context: the two modes (single-market and basket) and when to invoke each, plus a clear directive for when this tool should be used vs alternatives. It even explains the failure mode it prevents ('partial basket fills convert an arb into an unhedged directional position'), which is strong 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses concrete behavioral traits: it outputs compatibility warnings in two specific cases, tracks skipped_cross_type/subtype counters, provides temporal_alignment with an 'aligned:false' warning, and explicitly states that a zero match may indicate events are semantically unrelated. This is exactly the kind of contextual behavior that annotations alone cannot convey.

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

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

The description is long (≈350 words) but well organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence conveys essential info. It is front-loaded with the core purpose. Some redundancy exists (e.g., repeating 'pre-mapped ≠ tradeable' at the end), but overall it earns its length for a tool with three parameters and complex output semantics.

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

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

No output schema is provided, so the description fully compensates by explaining the response structure: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also explains how to interpret edge cases (no arb exists, events unrelated). For a complex tool with safety fields, this is complete and actionable.

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 per-parameter descriptions with 100% coverage, so the baseline is 3. But the description adds substantial meaning: it explains that `topic` is a pre-mapped shortcut auto-fetching matching events, that the explicit tickers override the mapped side, and gives concrete examples (e.g., 'KXFED-26OCT', 'fed-decision-in-june-825'). It also explains the relationship between the two modes, which the schema does not.

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, unambiguous purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the resource (cross-venue spread) and the two venues, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges. It also specifies the verb implicitly (compute/show) and clarifies that it only reports spreads when bet shapes are equivalent.

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 usage context: it explains the two modes ('topic' pre-mapped shortcuts vs explicit tickers), when each is appropriate, and warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning. It clearly states when spreads are meaningless (temporal misalignment, unmatched bet shapes). However, it does not explicitly name alternative tools to use instead, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds context about the output content ('full ingredients and cooking instructions'), which is useful beyond the annotations. No contradiction.

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

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

The description is concise—two sentences, front-loaded with the core function, followed by a clear usage instruction. Every word earns its place 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?

Given no parameters, an output schema, and a clear description of the result ('random meal recipe with full ingredients and cooking instructions'), the description is complete. It also differentiates from meal-related sibling tools.

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

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

The tool has zero parameters, and schema coverage is 100% (trivially). The description appropriately focuses on the output instead of parameters, matching the baseline for no-param tools.

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: 'Get a random meal recipe with full ingredients and cooking instructions.' The specific verb 'Get' and resource 'random meal recipe' with details on contents distinguishes it from sibling tools like search_meals and get_meal.

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 recipe inspiration without a specific search.' This implies when not to use it (when a specific search is needed), though it does not name alternative sibling tools directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details: the ability to list all keys by omitting the key argument, scoping to an identifier (anonymous IP, BYO key hash, or account ID), and the relationship with remember/forget. This goes beyond minimal annotation-driven expectations, but not to an extremely rich level, so a 4 is appropriate.

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

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

The description is four sentences, front-loaded with the primary action. Each sentence earns its place: it explains the two modes, gives usage context, mentions scoping, and ties to sibling tools. No redundant or vague phrasing. This is a model of concise, structured documentation.

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 one optional parameter and no output schema, the description is fully complete. It covers the two behaviors (get and list), provides illustrative examples of what to store, notes scoping, and explains when to use the tool relative to its siblings. 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?

The schema covers 100% of parameters with a basic description, giving a baseline of 3. The tool description enriches the 'key' parameter by providing concrete examples of key values (target ticker, address, research notes) and explicitly stating the behavior when omitted (list all keys). This adds meaningful semantic context beyond the schema, so a 4 is warranted.

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 action: 'Retrieve a value previously saved via remember, or list all saved keys'. It specifies the resource (a saved value or list of keys) and distinguishes it from sibling tools remember and forget with 'Pair with remember to save, forget to delete.' This makes the purpose unambiguous.

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

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

The description explicitly guides when to use the tool: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also explains the alternative actions (remember to save, forget to delete), providing clear usage context relative to siblings.

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

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

The annotations declare readOnlyHint: true, but the description explicitly says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which indicates a state-changing side effect. This directly contradicts readOnlyHint, making the behavioral transparency score 1 and triggering an annotation contradiction.

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

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

The description is four sentences, front-loaded with the main purpose, and each sentence adds unique value: payload contents, filtering options, mark_read side effect, and alternative access. There is 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?

With no output schema, the description sufficiently explains the return payload and key behaviors (filtering, mark_read, alternative endpoint). It covers the essential aspects for a 5-parameter tool, though the annotation contradiction could confuse an agent about side effects, slightly reducing completeness.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description adds value by providing an example for type ('sec_8k'), clarifying since as an ISO timestamp, and explaining the downstream effect of mark_read on future calls, which goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with details on the return payload (source, citation_uri, raw event payload). It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like recent_changes, so it earns a 4 rather than a 5.

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 by mentioning polling is supported and offers an alternative HTTP endpoint for scripts/dashboards. It implies when to use this tool (for polling) but does not discuss when to use it versus sibling tools, so it lacks explicit exclusions or 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 annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals rich behavior: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO; explains the GDELT preference and rate-limit fallback; notes USPTO soft-failure until reactivated; and describes returned data structure (changes[], total_changes, citation URIs).

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 adds value. It front-loads user intents and core capability, then efficiently covers data sources, fallback behavior, parameter syntax, return structure, and a sibling alternative—all in a compact paragraph.

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 explicitly outlines the return shape and data sources. It covers all key aspects needed for selection and invocation: what it does, how it behaves, parameter formats, fallback logic, and when to choose a different tool. The complexity is high, yet the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by showing the accepted formats for 'since' (ISO date or relative shorthand) and giving concrete examples for 'value' (ticker vs. CIK). It also recommends typical values, exceeding the schema's documentation.

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

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

The description opens with concrete user intents ("What's new with X") and defines the tool as a "change feed for a company in the last N days/weeks/months in ONE parallel call." It explicitly contrasts with entity_profile, so it distinguishes itself from a key 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?

The description provides explicit usage guidance: it tells the user when to use this tool (for real-time change updates) and when to prefer entity_profile (for static profiles regardless of window). It also gives practical parameter advice like "Use '30d' or '1m' for typical monitoring."

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

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

Adds valuable context beyond annotations: key-value pair scoping by identifier, 24-hour retention for anonymous sessions, persistent memory for authenticated users. No contradiction with idempotentHint or readOnlyHint.

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 tight sentences front-load the purpose, then give use cases, storage details, and sibling pairings. Every sentence earns its place with no redundancy or filler.

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

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

For a simple memory-store tool with no output schema and well-documented params, the description covers what it does, when to use it, how storage works, retention, and related tools. No gaps remain for an agent to select and invoke it correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds a general key-value framing but doesn't materially expand on the schema's own descriptions of key and value, staying at the baseline.

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

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

The description opens with a specific verb+resource pairing ('Save data the agent will need to reuse later') and clearly distinguishes itself from siblings by explicitly naming recall and forget. This makes the tool's role 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?

Provides explicit 'Use when' guidance with concrete examples (resolved ticker, target address, user preference) and mentions alternatives (recall to retrieve, forget to delete). Also clarifies persistence differences between authenticated and anonymous sessions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit reporting of unresolved identifiers. This is rich, transparent behavioral disclosure without contradicting 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 relatively long but well-organized, starting with relatable example queries, then stating the core purpose, then detailing supported types and edge-case behavior. Every sentence adds functional information, and the user-phrase preamble makes the tool's niche instantly recognizable. It is slightly wordy but justifiable for the tool's complexity.

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

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

Given there is no output schema, the description does an excellent job of setting expectations: it outlines the identifiers that will be returned (CIK, ticker, LEI, FIGI, RxCUI), how sources are labeled, how unresolved identifiers are handled, and how failures degrade. This gives an agent most of what it needs to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances the parameters by providing concrete examples (AAPL, 0000320193, ozempic), clarifying the mapping between type and expected value format, and explaining the output that each type produces. This goes beyond simply repeating schema definitions.

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

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

The description opens with concrete user queries, then explicitly states the core purpose: resolving a user-spoken name to canonical/official identifiers other tools require as input. It also details supported entity types (company, drug) and the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI), clearly distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces 2–3 manual lookups, indicating it's a bootstrap step. However, it does not explicitly name alternative tools or state scenarios where this tool should not be used, so it falls short of a 5.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it ranks by score, surfaces most/least recognized, and returns score, confidence, and signal density per entity—details not covered by annotations. It also reveals it calls ai_visibility_check internally.

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 compact sentences that front-load the primary action, then clarify the use case and output format. Every sentence adds value with minimal redundancy, achieving excellent conciseness for the tool's complexity.

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

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

Given no output schema, the description effectively covers the tool's purpose, process, use case, and return format (ranked list with score, confidence, signal density). It also references the underlying ai_visibility_check tool and the input constraints are already in the schema, making it complete for a read-only comparison tool.

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

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

The schema already provides 100% coverage with descriptions for all four parameters, including the special role of the first entity and the optional models/_apiKey/context. The description's phrase 'your brand + N competitors' reinforces entities semantics but does not add significant 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 uses a specific verb 'Compare' and explicitly identifies the resource: AI visibility across multiple entities side-by-side. It clearly distinguishes from sibling tools like ai_visibility_check (single entity) by emphasizing the comparative, multi-entity nature.

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 frames the use case for competitive AI-marketing audits with an example question ('does Claude know about us as well as our competitors?'). It does not explicitly list alternatives or when not to use, but mentioning it probes with ai_visibility_check implies the single-entity alternative exists.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant behavioral context beyond those flags: it fans out across two services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s and be reported in sources_failed. This is rich transparency about edge-case behavior without contradicting 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 long but well-structured: a clear purpose statement, explicit usage trigger, compact summary of return fields, ecosystem scope, and a failure-mode note. Every sentence contributes essential information, though the density might be slightly high for quick parsing. Still, it avoids redundancy and is well front-loaded.

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

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

For a composite tool with no output schema, the description fully covers the return structure (summary block fields, per-advisory detail, links, alternatives), the sources used, ecosystem limitations, and failure behavior. It also explains what happens on partial failures. This gives an agent everything needed to use the tool correctly without further inference.

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 both parameters are already described (package and version). The description adds meaningful nuance: 'version' defaults to the latest published version when omitted, and clarifies that 'package' expects npm package names (including scoped ones). This reinforces semantics but does not add new parameters or values.

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

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

The description clearly states the tool is a composite 'should I add this npm package to my project' check, naming specific sources (deps.dev, bundlephobia) and listing output fields. It distinguishes itself from siblings by being the only package-dependency analysis tool, and also clarifies the NPM-only scope and fallback to deps.dev:version for other ecosystems.

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 gives when to use it: 'Use whenever an agent asks...' with concrete example questions. It also provides exclusion guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells the agent exactly when to use this tool vs 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?

Adds detail on return content (category, ingredients, instructions, URLs) beyond annotations, which already declare non-destructive read-only behavior. No contradiction.

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

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

Single, front-loaded sentence with no filler; enumerates useful return fields 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?

Adequate for a simple search tool: annotations cover safety, output schema exists, and description covers return content; minor omission of list-vs-single result behavior is not significant given 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 fully documents the 'query' parameter with type and description; tool description's 'by meal name' adds no additional semantics beyond 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?

Clearly states it searches TheMealDB by meal name and enumerates returned fields, distinguishing it from siblings like get_meal (specific ID) and meals_by_ingredient (by ingredient).

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 clear use case (search by name) but does not explicitly mention when to prefer alternatives like get_meal or meals_by_ingredient, 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 readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and enforces a 200K char cap with truncation and flagging. This goes well beyond the structured fields, explaining internal mechanics and edge-case 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 tightly structured: the first sentence states the core function, the second gives usage context, the third provides an integration pattern, and the fourth covers technical details. Every sentence adds essential information without redundancy, wordiness, or trivial repetition of the tool name.

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 tells the agent exactly what to expect: 'top-N passages with character offsets and similarity scores.' It also covers input constraints (200K chars), windowing behavior, and truncation flagging. The pairing with ask_pipeworx_grounded provides a complete workflow, making the tool understandable in context without needing additional documentation.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds contextual meaning by giving concrete examples for 'text' (e.g., 'SEC 10-K body, an article, a long tool result') and for 'query' (e.g., 'supply-chain risk', 'fiscal year 2024 revenue'). It also implies 'limit' semantics by saying 'top-N passages' and 'returns only the passages that matter,' though the limit parameter itself is left to 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 and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by emphasizing it works on already-fetched text, not external sources, and explicitly differentiates the return type (top-N passages with offsets and similarity scores). It also references a companion tool (ask_pipeworx_grounded), further disambiguating its role.

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

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

The description gives explicit guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also provides an alternative/companion pattern: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells the agent when and how to use it versus 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?

Adds substantial behavior beyond annotations: requires OAuth account, feed is always on, phone verification requirement, 10/day SMS cap, and returns subscription id. Annotations are minimal (readOnly=false, idempotentHint=true), but the description enriches understanding of account prerequisites and delivery 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?

Dense but well-organized: opens with purpose, then prerequisites, supported types, and delivery channels. Every sentence carries useful information without fluff.

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

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

Given the rich schema and annotations, the description covers the essential workflow: creation, persistence requirement, return value, and delivery options. It omits webhook specifics which are fully documented in the schema, but overall is complete for a complex tool.

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

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

Schema covers all parameters with examples, so baseline is 3. The description adds extra semantics like items:["5.02"] = officer change and topic:"fed" context, which give meaning not fully captured 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 and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action and returning a new subscription id.

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 clear context: requires OAuth account, anonymous/BYO cannot persist, supported types. It doesn't explicitly state alternatives ('use list_subscriptions to view existing'), but the use case is well implied and the constraints are helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive intent. The description adds that results are 'drawn from the live catalog', implying dynamic and potentially changing output, and explains the no-arguments vs. topic-passing behaviors. This is useful context beyond the structured annotations.

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

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

The description is verbose but front-loaded with natural-language user queries, making it scannable for an agent. It packs a lot of information—categories, output shape, usage instructions—without wasted sentences. Slightly long but each element contributes to understanding.

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

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

Despite lacking an output schema, the description fully covers what the tool returns (category-bucketed example questions with tool and argument shapes), when to use it, and how to vary the call via the topic parameter. It is sufficiently complete for an onboarding/discovery tool.

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

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

Schema coverage is 100% with a clear description of the optional topic parameter. The description reinforces semantics by providing example values ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a cross-category spread, adding 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 opens with the user-facing intents ('What can I ask Pipeworx?', 'give me ideas') and clearly states it is the 'onboarding entry point' for discovering what to ask. It specifies the output as category-bucketed example questions with the exact tool and argument shape, thereby distinguishing it from sibling meta-tools like ask_pipeworx or entity_profile.

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

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

Explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides topic examples to focus the call and notes that omitting topic returns a full spread. Lacks an explicit 'when not to use' clause, but the directive to use it first establishes clear 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?

The description discloses that the operation is a soft delete ('deactivated, not deleted') and mentions the side effect on historical events. This adds behavioral context beyond the annotations (which only indicate non-destructive and idempotent hints), making the tool's behavior fully 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 concise at two sentences, front-loads the primary action, and uses the second sentence for necessary caveats without redundancy. Every word adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and side effects sufficiently. The ownership rule and soft-delete nature are critical context that is fully addressed.

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

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

The input schema already provides a complete description of the single 'id' parameter ('Subscription id (uuid) returned by subscribe'), so the description adds little semantic value for the parameter itself. The baseline of 3 applies 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 states a specific action ('Cancel a subscription by id') with a clear resource and method. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation, and also notes ownership enforcement and soft-deletion behavior.

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

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

Ownership enforcement ('you can only cancel your own subscriptions') provides clear context for when this tool is applicable. However, it does not explicitly name alternatives or state when not to use it, though the purpose is 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral details: the dual routing paths (SEC EDGAR vs grounded pipeline), the exact verdict enumeration, and — crucially — the semantics of could_not_verify (not evidence) and unsupported (no source coverage). This is highly valuable for safe usage.

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 somewhat long, leading with a list of synonyms that could be condensed into a single phrase like 'natural-language claim verification.' Still, every subsequent sentence adds substantive detail about routing, verdicts, and error semantics, so it's structurally efficient for the complexity.

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

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

With no output schema, the description carries the full burden of explaining return values and error states, and it does so thoroughly — verdict list, actual value, citation, reasoning, and the critical could_not_verify vs unsupported distinction. Combined with high schema coverage and annotations, it is contextually complete for an agent to safely 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?

Both parameters are fully documented in the JSON schema (100% coverage), including examples and default behavior. The description adds no additional parameter-level semantics beyond what the schema already provides; the mention of 'exact percent-delta math' and tolerance overrides is already in the schema. Thus a baseline 3.

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 claim verification tool with specific verbs ('verify', 'fact check') and resource ('natural-language factual claims' against 'authoritative sources'). It distinguishes itself by explaining the two routing paths and how it replaces 4-6 sequential calls, differentiating from sibling research tools.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delineates company-financial vs other claims, providing a clear use-case landscape. However, it doesn't explicitly name alternative tools for other use cases, so it's slightly below a 5.

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