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?

The description reveals meaningful behavior beyond annotations: it routes the question to one of 5,767 tools from verified sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. Annotations already cover read-only, open-world, and idempotent safety, so the remaining gaps are minor.

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

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

The description is front-loaded with the critical 'PREFER OVER WEB SEARCH' guidance and supported by concrete examples. It is somewhat long and contains mild redundancy around preferring it over web search, but every major section serves a distinct purpose: scope, behavior, examples, and sibling routing.

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

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

The description covers the tool's scope, usage, behavior, citations, and sibling alternatives, which is substantial for a routing-style tool without an output schema. It could be slightly more precise about the shape of the returned object, but the examples and citation note provide enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the single semantic parameter and its aliases. The description adds usage context—natural-language factual questions and domain examples—but does not need to explain parameter format because the schema already handles it.

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 ask_pipeworx as a factual question-answering tool that routes to authoritative structured data sources and returns cited answers. It differentiates itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research, so an agent can distinguish it without opening schemas.

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 tells the agent when to use this tool: for current or historical data, authoritative structured facts, and factual user queries, even overlapping with web search. It also specifies alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part queries, plus news routing behavior.

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 o the safety profile is known. The description adds key behavioral context beyond annotations: it is the experimental edge, candidates may be live during test, no candidate is currently active, and it is a full working router with no fallback. This is rich transparency that informs invocation despite volatile routing 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 three sentences with no filler. It front-loads the core identity ('Beta version of ask_pipeworx'), then covers current state, usage condition, comparison purpose, and fallback behavior. Every sentence 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 description is complete for a routing variant. It anchors to ask_peworx for arguments and response shape, explains the experimental nature and current status, and clarifies it is a fully functional router. Annotations cover safety, and no output schema is needed because response shape is explicitly said to match ask_peworx.

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 every parameter (question plus five aliases) is documented in the schema. The description only says 'same arguments' as ask_pipeworx, which does not add meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing it is the experimental edge, so an agent can tell them apart.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router to decide merges. It does not state an explicit when-not-to-use case, but the 'when you want the newest routing' condition is clear enough for selection.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool refuses to answer when data doesn't directly support an answer, lists exact refusal reasons, and notes the extra LLM call cost. This adds meaningful behavioral context that annotations do not capture.

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

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

The description is information-dense and efficiently structured: purpose first, then return format, refusal behavior, usage conditions, and cost tradeoff. Every sentence contributes operational value with no redundancy or filler.

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

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

With no output schema, the description fully specifies the return shape including success fields and refusal reasons. It also covers usage context, alternatives, and cost implications, making it complete for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100% and the schema already documents that question accepts aliases (q, query, prompt, text, input). The description does not add parameter-level semantics beyond reiterating that the tool fills arguments and fetches data. Since the schema fully covers the parameter meaning, a 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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb (ask) and resource (Pipeworx). It explicitly contrasts with ask_pipeworx by stating it EXTRACTS the answer using ONLY what the tool result contains, making the distinction between the two clear.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives concrete examples of high-stakes domains. It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' and explains the cost tradeoff of one extra LLM call.

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 provide readOnly/openWorld/idempotent/non-destructive hints. The description adds substantial context beyond that: required account/tier, decomposition into facets, parallel routing across 5,767 tools, the exact findings-packet shape, stable pipeworx:// citations, and explicit gaps[] that are 'never invented.' This is strong behavioral disclosure.

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 appropriately sized for a complex tool. It front-loads the critical auth constraint and then covers scope, mechanism, output, and alternatives. There is minor redundancy around the ask_pipeworx fallback, but overall each sentence 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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it explains what the tool returns, what it cannot do (open-web search), when it should not be used, and what inputs matter. An agent has enough context 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%, so the schema already documents question and depth. The description adds useful semantic context by emphasizing that broad/multi-part questions are the intended use and that 'thorough' requires a paid plan, which helps the agent choose question phrasing and depth level.

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 and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call. It also differentiates itself clearly from open-web search and from ask_pipeworx, making its scope unambiguous.

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

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

The description explicitly says when to use it: 'Best for broad/multi-part questions over structured data.' It also names alternatives and conditions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' This gives the agent actionable routing 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, 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?

Beyond the annotations, it discloses rich behavioral context: it fans out across multiple sources, returns per-company varying sections, soft-fails on the USPTO PatentsView API sunset, treats empty sections as real 'no data', and explains private-company resolution. This goes well beyond what readOnlyHint/openWorldHint 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 long but packed with signal — examples are front-loaded, and every sentence contributes details about sources, return fields, or edge cases. Minor redundancy exists around type/value interchangeability, but overall it remains effective for a complex multi-source 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?

There is no output schema, so the description carries the full burden of explaining return data. It enumerates all result sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, etc.), URI formats, source failure handling, and input resolution behavior. Nothing an agent needs 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 already documents both parameters fully (100% coverage). The description adds meaningful extra context: value can be a ticker, CIK, or company name; name resolution uses SEC EDGAR; type values are interchangeable; private companies yield resolved:false. This adds value beyond the schema, warranting a 4.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call', with concrete example queries. It clearly distinguishes this tool from single-pack lookups by emphasizing the holistic view, making the tool's purpose unambiguous.

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

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

It explicitly says to 'ALWAYS PREFER' this over chaining single-pack lookups when the user asks for a holistic view, giving solid when-to-use guidance. It also covers input forms and private-company behavior, but it doesn't directly compare against sibling tools like compare_entities or deep_research, so it stops short of a full 5.

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

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

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral disclosure: gross vs net spreads, Kalshi fees not modeled, token-overlap matching, compatibility codes, temporal-mismatch handling, unclassified leg exclusion, and skipped comparison counters. 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 thorough and front-loaded, but it is very long and somewhat repetitive — for example, temporal_alignment_unknown and compatibility_warning are emphasized multiple times. The density is justified by the tool's complexity, yet it exceeds what concise documentation would need.

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 compensates well by documenting the response shape, safety fields, compatibility codes, and return-value nuances such as gross spread and skipped pairs. The remaining gap is the unspecified zero-parameter/default invocation 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?

Schema coverage is 100%, but the description adds real value by enumerating all valid topic shortcuts, explaining that explicit parameters override the topic-mapped sides, and stating that both modes use the identical overlap matcher. It does not clarify the required combination of parameters or behavior when none are supplied.

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 defines a specific cross-venue spread between Kalshi and Polymarket for the same resolving question, with two distinct invocation modes. It is immediately distinguishable from the Polymarket-only sibling tools by its dual-venue 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?

The description clearly explains the two invocation modes — pre-mapped topic shortcuts versus explicit ticker/slug pairs — and warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly name alternative tools or state what happens when no parameters are supplied, but the mode selection context is strong.

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

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

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?

Beyond the hints (readOnly, idempotent, openWorld, non-destructive), the description discloses graceful degradation ('LEI/FIGI enrichment degrades gracefully'), ambiguity handling ('asserts nothing and returns figi_candidates'), and unresolved identifiers being explicit. This enriches the annotation profile and is consistent with it.

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

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

The text is long, but every clause earns its place: query examples, supported types, sources, ambiguity behavior, failure modes, and input constraints. It could be organized more tightly, but for the tool's complexity the density is justified and the key directive ('Use FIRST...') is front-loaded.

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

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

There is no output schema, yet the description covers what gets returned (CIK, ticker, LEI, FIGI, RxCUI, unresolved list, figi_candidates), the sources behind each, and when enrichment may be missing. Together with the rich annotations, an agent has enough to call and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it clarifies that value must be the entity name only (not the full noun phrase) and explains the bond/ISIN edge cases. It also maps type to the supported entity kinds and their output identifiers, well beyond the enum labels.

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

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

The description is anchored by a specific verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers,' and backs it with six concrete query phrasings. This makes the tool's unique role—name-to-ID conversion—unmistakable against siblings like entity_profile or compare_entities, so an agent can select it without opening schemas.

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 states the central trigger explicitly: 'Use FIRST whenever you have a name but need an ID,' and details accepted input formats (ticker, CIK, ISIN, name, brand/generic drug name). It stops short of naming when-not-to-use alternatives (e.g., after an ID is already known, use entity_profile), so the exclusion is implied rather than spelled out.

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.