Food Feeds

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond these: the default model (Workers AI Llama-3.3-70b), the free vs. paid billing model for Anthropic calls, and the fact that the API key is passed straight through. This gives agents insight into cost and side-effect implications.

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

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

The description is three sentences, front-loaded with the core action, followed by model options and use cases. Every sentence adds distinct value—purpose, configuration/billing, and output/use cases—with no fluff or repetition.

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

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

With no output schema, the description explicitly states the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers parameter behavior (default model, optional Anthropic key), use cases, and sample entity formats in the schema. For a read-only probe tool, this is complete and leaves no major gaps for an agent to infer.

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 parameters are already well-documented. The description adds context about the default model and the condition for using _apiKey, but this largely mirrors schema text. Thus the description provides only marginal additional meaning beyond the schema, meriting the baseline score of 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 opens with 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model,' giving a specific verb ('probe'), resource ('LLMs'), and output (visibility score). This clearly distinguishes it from sibling tools like ask_pipeworx (general Q&A) and scan_competitor_ai_presence (competitor-focused 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 states concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to pass '_apiKey' for Anthropic (BYO key). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool over siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds value without contradicting them: it discloses router behavior (auto-fills arguments), citation URI stability, tier accessibility, and that it works on every tier with one fast call. It does not detail failure modes or what happens if no tool matches, but for a read-only query router this is strong context.

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

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

The description is longer than average but every section earns its place: directive, scope, examples, default positioning, and step-up alternatives. It fronts the most decision-relevant instruction ('PREFER OVER WEB SEARCH') and keeps the examples compact. Slightly over-stuffed, but appropriate given the router's breadth.

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 required parameter, no output schema, and a complex routing role, the description covers everything an agent needs: what to pass (natural language question), how it behaves (routes, fills args, returns citations), when to use it (default for factual questions), and when to step up (grounded, deep_research). The examples help disambiguate edge cases like breaking news.

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

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

Schema description coverage is 100%, with each parameter alias documented under the question field. The description adds extra semantic value by clarifying the accepted natural-language request types, listing example queries across domains, and specifying that aliases such as query, q, prompt, text, and input are accepted.

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 identifies a specific verb ('Routes the question to the right one of 5,743 tools'), a clear resource domain (1500 verified sources across SEC, FDA, FRED, patents, etc.), and a concrete output ('structured answer with stable pipeworx:// citation URIs'). It explicitly contrasts with sibling tools like ask_pipeworx_grounded and deep_research, making differentiation immediate.

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

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

The description gives explicit when-to-use directives: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks... even if web search could also answer it', and 'START HERE for most questions'. It also states concrete step-up conditions, naming ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that: candidate routing improvements can be live, the tool may differ from stable while a candidate is under test, it currently matches ask_pipeworx exactly, and it is a full working router with no fallback. This materially helps an agent calibrate 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 a bit long but every sentence earns its place: it defines the tool, clarifies current active-candidate status, gives usage guidance, and resolves potential fallback concerns. It is front-loaded with the beta relationship and maintains clear structure throughout.

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 an experimental variant of a known sibling tool, the description gives enough context to select and invoke it correctly: same schema, same response shape, current equivalence to ask_pipeworx, and the live-experiment caveat. No output schema exists, but referencing the identical response shape of the stable tool compensates reasonably well.

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 every alias and the primary question parameter fully described. The description adds only that the arguments are the same as ask_pipeworx, which is useful but does not go beyond what the input schema already provides.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx: an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental routing candidate behavior, though it does not explicitly contrast with the sibling ask_pipeworx_grounded.

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 contrasts with the stable router used for comparison. The guidance is clear for choosing between beta and stable, though it does not spell out when to prefer the grounded alternative or exclude beta for stability-sensitive use.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description reveals the extraction mechanism, return shape with evidence and confidence, and the full set of refusal reasons. This gives the agent a precise model of what to expect on both success and failure paths, including the inability to answer.

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

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

The description is longer than average but every sentence earns its place: purpose, mechanism, return schema, refusal reasons, usage policy, and cost. It is front-loaded with the core value proposition and structured logically, though slightly dense in the middle.

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 compensates by fully specifying output structure, error/refusal behavior, and usage contexts. An agent has enough information to call this correctly and interpret any result, making the description comprehensive for its scope.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description doesn't need to add parameter-level detail since the schema fully explains the input; however, it doesn't further illuminate how the question is processed or formatted, 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 clearly identifies this as a hallucination-resistant, grounded answer mode that routes to the right tool, fetches data, and extracts an answer strictly from tool results. It explicitly contrasts with ask_pipeworx, distinguishing the grounded variant from its sibling and making its unique role obvious.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and when not to: 'prefer ask_pipeworx for casual lookups'. It also discloses the cost tradeoff, providing clear selection criteria against the sibling tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes far beyond them with concrete behavioral details: resolver confidence tiers, status codes (low_confidence_match, market_closed_or_inactive), fan-out behavior, wide-spread flag, news fallback mechanics, and resolution-rule risk. This is exceptional transparency for an agent.

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

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

The description is long but dense, with a clear hierarchy: purpose, classifiers, fan-out examples, response shapes, resolver contract, safety, resolution rules. Every section adds actionable detail. It earns its length for a complex tool, though it could be trimmed (e.g., the many fan-out examples) without losing core 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?

Given there is no output schema, the description fully compensates by documenting response shapes, resolver contracts, parent-event extraction, news fallback, safety short-circuits, and resolution-rule risk. An agent has enough context to invoke the tool, interpret results, and handle edge cases without 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 the schema already documents all three parameters with descriptions. The tool description mostly reinforces the schema by showing examples of market input forms and adding context about what the tool does with the parameters (e.g., fan-out for depth), but it doesn't add substantial new semantics beyond the schema's 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb and resource. It further clarifies scope with classifiers and fan-out examples, making it unmistakable what the tool does and how it differs from sibling tools like polymarket_edges or validate_claim.

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 for' phrases ('should I bet on X', 'what does the data say about Y') and gives rich contextual guidance for low-confidence matches, closed markets, and illiquid spreads. However, it does not name alternative tools for when NOT to use this one, leaving some ambiguity relative to sibling analyzers.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses data sources for each type (SEC EDGAR/XBRL 10-K data; FAERS/FDA/trial counts), mentions correct handling of off-calendar fiscal years (AAPL Sep, NVDA Jan), explains sorting by primary metric, and states the output includes paired data plus citation URIs. This is rich behavioral context.

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

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

The description is dense but well-structured, starting with user intent phrases and then covering operational details. Every sentence adds value, but it is somewhat long and could be slightly tightened. It is still front-loaded and organized effectively.

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 input semantics, data sources, sorting, and output highlights (paired data + citation URIs). It lacks a precise output format description or error handling details, but it is nearly complete for its 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?

The description adds significant meaning to the 'type' parameter by explaining exactly what data each enum value retrieves (10-K metrics vs adverse-event/trial counts). It also clarifies 'values' by distinguishing tickers/CIKs from drug names with examples, enriching the schema's basic 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's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes specific trigger phrases like 'X vs Y' and 'rank these companies', and explicitly distinguishes it from sequential single-pack lookups.

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

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

Provides explicit usage triggers ('Compare X and Y', 'which is bigger', 'head to head'), states the entity count range (2–5), and gives a strong preference directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This clearly tells when to use this tool over alternatives.

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

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

Annotations only declare readOnly/openWorld/idempotent/non-destructive, but the description adds substantial behavioral context: account and paid-tier requirements, 15-90s latency, gaps[] never-invented behavior, contradiction detection, hop fields, fetchable citation_uri semantics, semantic excerpting, and the explicit 'NOT open-web search' boundary. This far exceeds what annotations alone convey and does not contradict 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?

Although long, the description is dense and every sentence carries operational significance: auth prerequisites, primary use case, alternative routing, internal behavior, output contents, latency, and citation guarantees. It is front-loaded with the account requirement and the critical distinction from ask_pipeworx, so the most decision-relevant information appears first.

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

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

With no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also covers prerequisites, expected latency, data-source scope, and when results will be empty. An agent has everything needed to invoke this tool correctly and set user expectations.

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

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

The input schema already documents both parameters and the depth enum with 100% coverage. The description still adds value by clarifying that `question` should be broad/multi-part ('decomposition is the point') and by attaching real-world consequences to `depth` choices, such as paid-plan requirement, latency expectations, gap-recovery behavior, and contradiction scans.

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: 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in ONE call, and immediately distinguishes itself from open-web search and from the sibling ask_pipeworx. It also explains the internal mechanics (decomposition, parallel routing, findings packet), so an agent knows exactly what this tool is and is not.

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

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

The description explicitly states when to use it ('Best for broad/multi-part questions') and when not to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives concrete example questions and names the alternative tool, leaving no ambiguity about selection.

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

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

Annotations already declare this as a safe, idempotent read operation (readOnlyHint=true, destructiveHint=false). The description adds behavioral value by disclosing that results are ready to call directly, include curated examples, and require no second schema lookup. This goes beyond the annotations' basic safety profile.

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 core purpose and structured logically: purpose, use cases, return format, and when-to-call guidance. The cited domain list is long but informative; every sentence adds value, though it could be tightened slightly.

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 discovery tool with no output schema, the description fully explains what it returns (top-N tools with names, descriptions, schemas, examples) and how results are ready to call. It also covers when to use it ('many tools available', 'not just one answer'), making it self-sufficient for an agent.

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

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

Schema description coverage is 100%, with clear descriptions for query and limit, including aliases and default/max values. The description's references to 'describing the data or task' and 'top-N' add little beyond the schema. Baseline 3 is appropriate because the schema already fully documents parameters.

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

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

The description clearly identifies the tool as a meta-tool for discovering other tools: 'Find tools by describing the data or task.' It specifies the resource (tools), the action (discover/find), and the scope (returns names, descriptions, schemas), distinguishing it from sibling tools that perform direct searches or analyses.

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

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

Provides explicit when-to-use guidance: 'Use 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 (not just one answer).' This gives clear context, though it does not name specific alternatives or exclusion 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?

Even with readOnlyHint, idempotentHint, openWorldHint, and destructiveHint already in annotations, the description adds substantial behavioral context: the USPTO PatentsView API sunset and soft-fail behavior, FDA results being limited to biologics, empty sections being a real 'no data' rather than a bug, and sources_used/sources_failed semantics. This goes far beyond what annotations alone convey.

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

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

The description is dense and long, but nearly every clause adds necessary information for a tool with no output schema and many return sections. It is front-loaded with user-phrasing examples and the core purpose, and the later sections are organized by source. The length is earned, though it could benefit from light formatting to make it scannable.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: it enumerates cik/company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers error-like outcomes (private companies, empty sections, API sunset), making it complete for an agent to invoke 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it clarifies that 'company' and 'ticker' are interchangeable, explains that value can be a ticker, CIK, or name, and specifies how name resolution works via SEC EDGAR. It also gives concrete examples and describes the private-company resolved:false 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 concrete natural-language triggers ('Tell me about X', 'research Acme', 'brief me on Tesla') and then states the exact function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (US public company) and the scope (multiple cross-sources), and distinguishes itself from chaining single-pack lookups.

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

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

It gives an explicit directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also handles exclusions and edge cases: private companies return resolved:false rather than a bare failure, and person/place queries are marked as coming soon. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnly and idempotent hints. The description adds 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway', disclosing resilience behavior beyond the annotations. It also mentions normalization but does not detail output structure.

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 concise sentences. The first sentence states the core purpose, and the second adds a key usage tip and behavioral note. Every sentence earns its place with no wasted words.

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

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

For a tool with no output schema, the description covers purpose, usage guidance, and a key behavioral fallback. However, 'normalize' is vague and the return format is not explained, which is a minor gap.

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

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

Schema description coverage is 100% with detailed descriptions for url, limit, and query. The description does not add any additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Fetch and normalize any RSS / Atom / RDF feed by URL' with a specific verb and resource. It also distinguishes from sibling tools like list_feeds by explicitly directing users to use list_feeds first for curated sources.

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

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

The description provides explicit guidance to use list_feeds first for curated sources, which is an alternative. It implies general use for fetching any feed URL but does not explicitly mention when not to use this tool or compare with read_feed.

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 cover destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar is lower. The description adds minor context ('previously stored', 'clear sensitive data') but doesn't disclose additional behavioral details like irreversibility or error handling. It is consistent with annotations.

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

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

Three sentences, front-loaded with the core action, and every sentence adds value—purpose, usage trigger, and sibling pairing. No fluff.

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

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

The tool is simple (one required param, no output schema) and annotations cover safety/destructive profile. The description includes purpose, usage guidance, and sibling relationships, making it complete for invocation.

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

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

Schema description coverage is 100% ('Memory key to delete'), so the description doesn't need to compensate. The description's 'by key' is redundant with the schema, adding no extra meaning. 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 uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly differentiating from siblings like 'remember' (store) and 'recall' (retrieve). It states exactly what the tool does.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also names complementary tools ('Pair with remember and recall'), providing clear contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the internal steps: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output shape as 'a single text blob ready to drop at site-root/llms.txt.' This adds value beyond the annotations without contradiction.

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

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

The description is three sentences, with the first stating the core purpose, the second detailing the process, and the third listing use cases. Every sentence earns its place—no fluff, clear front-loading, and appropriately sized 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?

The tool is simple (2 params, no output schema), and the description sufficiently covers what it does, how it works, and the expected output format. It does not explain edge cases like unreachable URLs or rate limits, but given the rich annotations and schema, this is not a major gap. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage for both parameters (url and max_links), so the baseline is 3. The description does not add any additional parameter semantics beyond saying 'for any URL,' which is redundant with the schema. It does not describe max_links behavior, but the schema already covers that, so no penalty.

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: 'Generate a production-ready llms.txt file for any URL.' It clearly explains the process (fetches page, extracts title/description/key links) and the exact output format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on auditing rather than generating a file.

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 'Useful for' list with three concrete scenarios: getting a client's site indexed, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. This gives clear context on when to use the tool, but it does not explicitly name alternative tools or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds useful context by noting the feed is curated and listing the exact fields returned. It also hints at the relationship to read_feed. No contradictions with annotations.

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

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

Two tight sentences with no filler. The first sentence states the core function and fields; the second covers filters and the handoff to read_feed. Every word 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 low complexity (2 optional params, no output schema), the description adequately covers the return fields, filters, and next-step guidance. Minor gaps like pagination or ordering are not critical for a simple listing 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 descriptions for both query and category. The description's mention of 'filter by category (food) or keyword' directly maps to the schema, adding no new semantic depth beyond what the schema already provides.

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 curated food & dining feeds with specific fields (id, title, category, source). It distinguishes itself from siblings like read_feed by mentioning the next step, making the purpose unmistakable.

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

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

It provides a clear usage context: list feeds with optional filters, then pass an id to read_feed. However, it doesn't explicitly contrast with other list-type siblings like list_subscriptions or fetch_feed, so the guidance is good but not exhaustive.

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, covering the safety profile. The description adds useful behavioral context by disclosing that it returns only active subscriptions by default and includes fields like fire_count, which goes 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 two sentences, front-loaded with the purpose, then lists return fields and use cases. Every sentence adds value, with no fluff or redundancy.

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

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

The tool is simple (one optional parameter), and although there is no output schema, the description explicitly lists all return fields. It also explains practical use cases. Minor gaps like pagination or limits are not critical for this straightforward read-only list 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% and includes a description for include_inactive. The description does not add new meaning for the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It specifies the verb (list), resource (subscriptions), and scope (caller's active). It also enumerates the returned fields, distinguishing it from sibling subscribe/unsubscribe 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 clear context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies using it before subscribing or unsubscribing, but it does not explicitly state when not to use it or name alternatives 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 are all false (readOnly, openWorld, idempotent, destructive), so the description carries full behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota behavior ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and reading cadence ('team reads digests daily'). This adds significant context beyond annotations without contradiction.

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

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

The description is longer than average but every sentence earns its place. It is front-loaded with the core purpose, followed by usage categories, exclusions, token behavior, rate limits, and cost. No filler or redundancy; the structure flows logically from what → when → how → constraints.

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 fully covers the tool's return behavior (claim_token and later status), input parameters (type, context, message, claim_token), exclusions, rate limits, and operational cadence. It is self-contained and leaves no major ambiguity for an agent selecting or invoking 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 coverage is 100%, so baseline is 3. The description adds value beyond schema: it explains claim_token usage with a concrete example, instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' for the message/context fields, and clarifies acceptable message length ('1-2 sentences typical'). This goes beyond the schema descriptions, though the schema already documents each parameter effectively.

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 as a feedback submission mechanism and distinguishes it from sibling tools like ask_pipeworx or discover_tools by explicitly limiting scope to Pipeworx-served tools and contrasting with other MCP servers.

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

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

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

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 though annotations already declare this a safe read-only operation, the description adds substantive behavioral context: data source ('derived from CF analytics-engine'), privacy ('no PII'), output shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). These details meaningfully go beyond the annotations and help the agent anticipate results.

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: the main statement is front-loaded, followed by a bulleted 'Useful for' section and a final note on data provenance. It's slightly long but every sentence contributes value. No fluff or filler.

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

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

Given the tool's simplicity (one optional parameter, no output schema, no nested objects), the description is thorough. It explains what the tool returns, the window options, use cases, and even the data source and caching. Since there is no output schema, the description successfully conveys the return shape ('top tools, top packs, total call volume') and the tuple structure.

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 window parameter with its enum and explanatory description ('shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description repeats this in the opening line but adds no new meaning. Schema coverage is 100%, 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 opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then explicitly states the return value ('top tools, top packs, and total call volume') and the time window options. This distinguishes it from siblings like discover_tools (which likely enumerates available tools) and ask_pipeworx (a Q&A tool).

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 'Useful for' list provides three concrete scenarios: discovering hot data sources, confirming canonical tools, and checking alignment with other agents. This gives clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, 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?

Goes far beyond the annotations (readOnlyHint, idempotentHint) by disclosing internal checks: partition filter with placeholder fraction threshold, semantic anchor with Jaccard similarity, fill-check logic that prices against live CLOB depth and warns against trading when realizable edge ≤ 0, and behavior when partition signal fires. This is rich behavioral context that helps an agent anticipate results and avoid false signals.

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 substantial but well-structured with clear section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and concise, information-dense sentences. Every paragraph adds necessary operational detail without redundancy, and key mode guidance 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?

For a tool with three modes, multiple filters, and a fill-check step, the description covers usage nuances, edge cases (placeholder slugs, low similarity, thin legs), response fields, and safety warnings. With no output schema, the description provides the necessary details about return structure and interpretation, making it complete for an agent to call and understand results.

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

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

Although the schema already describes both parameters (100% coverage), the description adds deeper meaning: explains the difference between event and topic modes, what kind of input each expects, the type of analysis each performs, and the exact scenarios for using them. It also clarifies that both are optional and what happens when neither is passed.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It also distinguishes between the three modes (trending_scan, event, topic) and references the alternative tool polymarket_fill_risk for custom sizing, making it clear what this tool uniquely does.

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

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

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also gives concrete examples (event slugs, seed questions), explains what cross-event mode catches that single-event misses, and directs users to polymarket_fill_risk for custom sizing.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond by detailing caching behavior ('Cached 1h at the KV level keyed on all knobs'), the edge calculation methodology per segment (lognormal barrier, GDELT ratio, overround with per-sport α), the 24h-move warning, and the diagnostics structure for empty segments. No contradictions with annotations.

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

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

The description is heavily structured and front-loaded with purpose before diving into segments. It uses clear visual grouping (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS) and is technically dense. However, it is very long; while most sentences carry useful information, a shorter summary of model families could have preserved clarity for agent consumption.

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

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

With no output schema, the description fully covers the return structure: top-level by_segment with three segments, fed_candidates/fed_note, and _diagnostics explaining why segments are empty. It also explains caching and the per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread). This is complete for a complex, 9-parameter tool with no 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 already covers 100% of parameters with descriptions, establishing a baseline of 3. The description adds valuable cross-parameter semantics: min_partition_leg_kelly is explained as necessary because partition arbs always return kelly_fraction_half=0 at the parent level, and slippage_pp is contextualized with Polymarket fee/liquidity assumptions. This elevates it to 4, though not 5 because the schema already handles basic semantics.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames it as 'what should I bet on today,' clearly distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by describing its three response segments and model families.

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

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

The description gives clear usage context: it's built for opportunity discovery without paging hundreds of markets, and it explains tradeable-edge knobs like min_liquidity/max_spread_pp and the fed_candidates exclusion. However, it doesn't explicitly name when-not-to-use or compare with sibling tools, so there's no strong exclusion 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?

Even with strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral detail: 60-day TTL, cache-miss snapshot writing, daily closes not intraday, and the signed edge_pp_net semantics (negative = SELL YES). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and uses clear ARGS, RESPONSE, and LIMITS sections. It is dense but every section provides operational value; the 'wide for a reason' analogy is illustrative but slightly extraneous, keeping it from a perfect 5.

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

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

With no output schema, the description fully documents the return structure (tracked[], expired[], snapshot_dates[]) including field meanings, edge-case semantics, and limitations. It also covers parameter defaults and data availability gaps, making the tool self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats defaults for days and window but does not add new semantic meaning beyond the schema. It omits the minimum clamp value for days that the schema includes, though this does not harm usability.

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 provides 'edge persistence and decay telemetry' and explicitly answers the question 'how long has this edge existed and is it shrinking?'. It differentiates itself from the sibling polymarket_edges tool by being built from its daily snapshots and focusing on historical persistence rather than current edges.

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

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

The description gives clear context for when to use the tool ('Answers how long has this edge existed and is it shrinking?') and contrasts it with fresh vs stale edges. It references the relationship to polymarket_edges snapshots, but does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral detail beyond those: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), names 'thin_legs' and 'forced_directional_risk' in basket mode, and explains how size_usd is interpreted differently in each mode. This is substantial contextual 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 long but information-dense, with mode-specific details, return fields, and risk rationale all earning their place. It is front-loaded with purpose and requirements before elaborating on each mode. It could be slightly tightened, but every sentence adds meaningful guidance.

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?

This is a complex tool with no output schema, yet the description thoroughly enumerates what the caller receives: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, and forced_directional_risk. It also explains failure modes and the danger of partial fills, making it complete for an AI 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds meaning by clarifying conditional requirements (market or event), mode-dependent side defaults (auto in basket), and the dual interpretation of size_usd (max spend on buys vs target proceeds on sells, settlement notional in basket). This exceeds 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 purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool from sibling tools by naming polymarket_arbitrage and polymarket_edges as consumers of the output, and it separates single-market vs basket modes with concrete semantics.

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

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

Usage is explicit: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when each mode applies (single-market vs basket), how defaults are chosen, and why using it is important (theoretical overround not capturable on thin books, partial fills convert arb to directional risk).

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

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

The description goes far beyond the annotations by explaining the matching algorithm, compatibility codes, null semantics for temporal_alignment, limitations of gross spreads, skipped counters, and unclassified leg handling. It also explicitly warns that pairing is keyword-based and not verified by a shared resolution source, which is exactly the kind of behavioral caveat an agent needs.

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 it is organized with labeled sections and every section contributes safety-relevant or operational information that is not available elsewhere. Some repetition and heavy parentheticals could be tightened, but the length is largely justified given there is no output schema and the tool has many edge-case behaviors.

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 and substantial behavioral complexity, this description is remarkably complete. It documents response fields, compatibility code semantics, skipped leg categories, fee caveats, spread sign convention, and what null means in temporal_alignment. An agent has enough context to call the tool and interpret its 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%, so the baseline is 3, and the description adds real meaning on top: it explains that topic is a pre-mapped shortcut, that explicit ticker and slug override the mapped side, and that both modes run the same matcher. It does not redefine the schema but gives the parameters practical semantics and relationships.

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 resource and objective: cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly explains the two modes and what the tool returns, but it does not explicitly distinguish itself from sibling tools such as polymarket_arbitrage, so the purpose is clear without being explicitly differentiated from close alternatives.

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

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

The description gives unusually clear guidance on how to choose between topic shortcuts and explicit pairings, and it warns that pre-mapped topics are not inherently tradeable. It does not name alternatives like polymarket_arbitrage or polymarket_edges or state when this tool should be preferred over them, but the situational context for invoking it and interpreting results 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=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that the tool returns normalized items with specific fields (title, link, published, summary) and supports optional keyword filtering—information not present in the annotations and useful for downstream processing.

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 exactly two sentences, with the primary action stated upfront. Every clause carries information: the id source, the return format, and the optional filter. No wasted words or repetition of schema details.

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

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

This is a simple, low-complexity read tool with all parameters documented in the schema. The description covers the resource identity, return type, and an optional behavior. There is no output schema, so the explicitly listed return fields (title, link, published, summary) fill that gap adequately.

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 descriptions for all three parameters (100% coverage), including the fact that 'feed' comes from list_feeds. The description adds minimal extra semantics beyond a general 'keyword filter' phrase, so it does not elevate above the schema-driven 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 ('Read') and a specific resource ('curated food & dining feed'), and clarifies the identifier source ('from list_feeds'). This distinguishes it from siblings like fetch_feed by domain and by the fact that it reads a managed feed rather than fetching arbitrary URLs.

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 implies a workflow: first call list_feeds to obtain the id, then read_feed. It does not explicitly name alternatives or state when not to use it, but the clear prerequisite ('from list_feeds') gives the agent enough contextual guidance for typical 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, idempotent, destructive=false), the description adds critical behavioral details: the 'omit key' listing behavior and the scoping to an identifier (anonymous IP, BYO key hash, or account ID). This explains privacy and namespacing, which annotations do not convey.

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

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

The description is three sentences, each with a distinct purpose: function, use case, and scoping/companion tools. It is front-loaded with the primary action and free of filler or repetition.

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

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

For a simple retrieval tool with one optional parameter and strong annotations, the description covers the essential behaviors (retrieve, list, scope, pairing). It lacks explicit error/return value details, but the absence of an output schema and the tool's simplicity make the description adequate.

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 fully describes the 'key' parameter (including 'omit to list all keys'), so the description doesn't add new parameter semantics. The examples of key contents are helpful but redundant to the schema's coverage.

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

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

The description clearly states the tool's function with specific verbs: 'Retrieve a value previously saved via remember' and 'list all saved keys'. It distinguishes itself from sibling tools by explicitly naming remember (save) and forget (delete), making the tool's niche 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 provides clear usage context: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes) and contrasts with re-deriving data. It implies the when-not-to-use by mentioning the companion tools (remember/forget), though it doesn't explicitly list exclusion scenarios.

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, so the safety profile is clear. The description adds valuable behavioral context beyond annotations, such as the effect of mark_read on subsequent calls (only newer events shown) and the fact that the feed is also available via an HTTP endpoint for external use. This enriches the agent's understanding 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 five sentences, each earning its place: purpose, return contents, filtering, mark_read behavior, and polling/alternative access. The key action is front-loaded in the first sentence. There is no redundant language or fluff, making it highly efficient.

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 by specifying that each alert carries source, citation_uri, and the raw event payload. It also covers filtering and mark_read semantics, which are critical for use. It does not explicitly mention the unread_only parameter, but the schema covers that, so it's not a gap. The description is complete enough for an agent to use the tool effectively.

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 each parameter is documented in the schema. The description adds extra meaning by explaining the interaction between mark_read and future calls, which is not obvious from the schema alone. It also gives a concrete example for the type parameter ('sec_8k'). This goes beyond the schema's baseline value.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It further clarifies the exact nature of the tool by explaining it returns the most recent alerts written by the evaluator, which distinguishes it from generic feed readers like fetch_feed or read_feed.

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 for use: filtering by type and since, marking events read, and polling. It explicitly states 'Polls work fine,' giving a direct usage recommendation. However, it does not explicitly mention when to use this tool over sibling tools like fetch_feed or read_feed, 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses significant behavioral traits: it fans out to SEC EDGAR, GDELT/GNews, and USPTO in parallel; details the fallback order and failure mode (PatentsView API sunset soft-fails); and notes the source grouping in results. This adds substantial transparency 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 dense but every sentence adds value. It opens with relatable query examples, then concisely explains data sources, parameter formats, return structure, and the alternative tool. The use of punctuation (dashes, parentheses) packages information efficiently without being verbose.

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 (fans out to multiple sources, no output schema), the description adequately explains the high-level return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. However, it does not detail the shape of individual change objects, which would be useful given the lack of an output schema. Still, the description covers the core behavior and limitations.

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 all parameters 100%, but the description adds practical detail: 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y'), 'value' can be ticker or CIK, and 'type' is restricted to 'company'. This enhances usability over raw 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 defines the tool as a change feed for a company over a time window, using specific verbs like 'What's new' and 'latest on'. It explicitly distinguishes itself from the sibling tool entity_profile by stating when to use that instead, making the purpose unambiguous.

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

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

The description provides explicit usage context with example queries ('What's new with X', 'updates on Acme') and directly names the alternative tool: 'Use entity_profile instead when you want the static profile'. It also explains the internal fallback logic (GDELT preferred, GNews when rate-limited), which guides appropriate usage.

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 idempotentHint=true and readOnlyHint=false. The description adds key behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This explains persistence and auth-dependence, which the agent needs to know.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: purpose, usage conditions, and storage behavior with sibling references. No wasted words.

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

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

The tool has no output schema, but the description covers the key behavioral aspects: scoping, persistence, and related tools. It does not mention return values or error conditions, but for a simple save operation these are not heavily needed. The description is sufficiently complete 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 coverage is 100%, with both 'key' and 'value' already described with examples in the input schema. The description only says 'key-value pair' and does not add further parameter-specific details, so it does not exceed the 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 states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It gives concrete examples (resolved ticker, target address, user preference) and explicitly distinguishes from sibling tools by referencing 'recall' and 'forget' for retrieval and deletion, respectively.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward...' and names alternatives with 'Pair with recall to retrieve later, forget to delete.' This tells the agent exactly when to use this tool and when to use siblings.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false, so the safety profile is covered. The description goes well beyond that by disclosing multi-source cascading lookups, ambiguity handling through figi_candidates, explicit unresolved fields, ISIN-to-LEI mapping, and graceful degradation when GLEIF/OpenFIGI are unavailable. This is substantive behavioral context, not a repeat of annotations.

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

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

The description is front-loaded with example queries, the 'Use FIRST' directive, and a clear SUPPORTED TYPES structure. However, it is quite long and some clauses are redundant or editorial, such as the extended bond-issuer explanation and the closing 'replaces 2-3 manual lookups' remark. It earns its density mostly, but not every sentence is strictly necessary.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does: named identifiers per type, source attribution, unresolved handling, ambiguity candidates, and failure modes. Both company and drug resolution paths are covered with examples. An agent can predict what it will receive and how to interpret edge cases.

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 still adds value beyond it by broadening accepted company inputs to include ISIN, which the schema's value description omits. It also explains semantic nuances like resolving non-equity instruments and why an ambiguous issuer name should return figi_candidates. The schema's 'entity name only' warning plus the description's identifier-source semantics together make parameter meaning unusually clear.

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 example queries and states the verb-resource pair clearly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' Supported types ('company', 'drug') and the product of resolution (CIK, LEI, FIGI, RxCUI, etc.) make the tool unmistakable. It also implies differentiation from sibling tools like entity_profile or search_within by framing itself as the identifier-producing precursor.

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 gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' This is strong guidance and explains why the tool exists relative to downstream tools. It does not explicitly name sibling tools or say when not to use it, so it falls just short of a 5.

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

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

Annotations already cover read-only/idempotent safety, and the description adds meaningful behavioral context: it internally probes each entity with ai_visibility_check and ranks results. It does not discuss rate limits or potential external API costs, but the disclosed delegation and scoring logic go beyond 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 with no fluff: the first states the core function, the second explains the method and output, and the third provides a real-world use case. Every sentence earns its place and key details 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?

Even without an output schema, the description discloses the return format (ranked list with score, confidence, signal density per entity). It also explains the internal process and gives a practical scenario. Combined with full schema parameter documentation, it provides sufficient context 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond schema; it confirms entities are brand + competitors, but the schema already documents each parameter clearly. No extra meaning is provided for models, _apiKey, or context.

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

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

The description clearly states a specific action ('Compare AI visibility across multiple entities side-by-side') with a defined resource and scope. It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison, ranking, and surfacing most/least recognized entities.

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

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

Provides clear context with a concrete example ('does Claude know about us as well as our competitors?') and frames it as a competitive AI-marketing audit. However, it does not explicitly mention when not to use this tool or name alternative tools like compare_entities, so it lacks exclusion guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses latency behavior ('first measurement on a new version can take 5-30s'), failure/degradation semantics ('sources_failed will list it if it times out, the rest still returns'), and the exact structure of the return value. 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?

The description is dense but every sentence carries useful information: core purpose, fan-out sources, use cases, ecosystem scope, return fields, and failure behavior. It is front-loaded with the primary action and remains efficient for the complexity of the 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?

Given there's no output schema, the description comprehensively lists return fields (summary block, advisory detail, links, alternative versions) and edge cases (new-version latency, partial failures). The ecosystem limitation and fallback guidance round out the contextual picture for an agent.

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

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

The schema already fully describes both parameters: 'package' is the npm package name and 'version' defaults to latest when omitted. The description does not significantly add new parameter semantics beyond what the schema covers, leaving the baseline of 3 appropriate.

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

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

The description opens with a specific verb+resource phrase: a composite check for whether to add an npm package, and explicitly names the data sources (deps.dev, bundlephobia) and the question it answers. It clearly distinguishes itself from sibling tools by focusing on npm dependency vetting rather than competitive scans or market research.

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

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

It explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing direct when-to-use guidance. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative path.

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 implementation details beyond the read-only annotation: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character cap with truncation flagging, and the presence of offsets for verification. These details help the agent predict performance and failure modes, adding significant value over the annotation's mere read-only hint.

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 core purpose and is dense with useful information: use case, pairing, mechanism, and limits. Every sentence earns its place, though the density and length make it slightly less concise than the two-sentence gold standard. It remains highly readable and well-structured.

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

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

For a tool with no output schema, the description fully discloses the return format (top-N passages with character offsets and similarity scores) and the edge case of input truncation with a flag. It also explains how it integrates with the broader tool ecosystem (fetch with gateway, ground with ask_pipeworx_grounded). This is complete for effective selection and invocation.

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

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

The schema already covers all three parameters with examples, so the baseline is 3. The description adds contextual meaning by explaining the 'text' parameter as a previously fetched record (e.g., SEC 10-K, article) and clarifies the 'query' with concrete examples. It also mentions the truncation flag, which elaborates on the 'text' cap. Thus it exceeds the baseline slightly.

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: "Semantic search INSIDE a fetched record." It clearly distinguishes from siblings by explaining the use case (searching inside an already-fetched record) and explicitly pairs with ask_pipeworx_grounded as the complementary tool. This prevents confusion with other query-based 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 states when to use the tool: "when the record is too big to cram into the prompt." It also names the alternative workflow with ask_pipeworx_grounded, explaining the distinction between fetching and grounding. This gives the agent explicit decision criteria and compares against a sibling tool.

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

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

Description discloses auth prerequisites, delivery constraints (phone verification, 10/day cap), webhook signature details, auto-disable after consecutive failures, and one-time secret. It is consistent with annotations and adds significant context beyond readOnly/idempotent/destructive hints.

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

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

The description is dense but purposeful, with a clear topic sentence followed by type catalog and delivery details. It is longer than necessary for a simple tool, but here complexity justifies the compact format; no filler sentences.

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?

Description covers purpose, return value, auth requirements, subscription types with embedded parameter examples, delivery channels, and edge-case behavior (webhook disable, one-time secret). With no output schema, this provides a complete picture 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?

Though input schema already documents all parameters, description enriches semantics with real examples (items:['5.02']=officer change), nested param shapes for each subscription type, and delivery caveats like 'must match verified phone' and 'auto-disabled after 10 consecutive failing runs'. This adds meaning beyond the schema's generic 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 uses the strong action verb 'Create' with the resource 'proactive monitoring subscription' and states the return value (subscription id). It clearly distinguishes from siblings like list_subscriptions, unsubscribe, and read_feed by focusing on creation.

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 explains when subscriptions can be created (requires Pipeworx OAuth account, excludes anonymous/BYO) and what types are supported with examples, but does not explicitly name sibling tools as alternatives. The guidance is clear enough for an agent to select this over list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: returns live-catalog-derived content with exact tool/argument shapes, and the parameter behavior. No contradictions.

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 fairly long but front-loaded with example queries and key info. Each sentence adds important detail, though some trimming of example enumeration could improve efficiency.

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

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

No output schema, so description covers return values ('Returns category-bucketed example questions...'). Also covers parameter behavior and when to use. Complete for onboarding tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples ('finance', 'pharma', 'betting') and clarifies the effect of topic, adding value beyond the schema.

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

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

The description clearly states the tool's function with specific verbs: 'the onboarding entry point... Returns category-bucketed example questions... each with the exact tool + argument shape that answers it.' It distinguishes from siblings by focusing on question suggestions and learning meta-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?

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' Also specifies when to pass topic vs no arguments.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals ownership enforcement, that the row is deactivated rather than deleted, and that historical events remain available. These are non-obvious traits not captured by the annotations (readOnlyHint, destructiveHint, idempotentHint). The description is consistent with the annotations, with no contradictions.

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, front-loaded with the core action, followed by essential transaction details. No redundant words, no repetition of annotations, and every clause adds meaningful information. Excellent conciseness.

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 single-parameter mutation tool, the description covers the action, authorization boundary, and side effects (soft delete, historical data retention). With annotations providing safety and idempotency hints, and no output schema required, the description is sufficiently complete 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 input schema already fully documents the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe.'). The tool description merely restates 'by id' without adding new format, constraints, or behavioral details. Since schema coverage is 100%, the baseline of 3 applies, and there is no added value from the description.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It specifies the resource (subscription) and the operation (cancel), and the ownership enforcement distinguishes it from other subscription-related tools like subscribe or list_subscriptions. The purpose is 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 implies usage: this is the tool to cancel a subscription you own. It explicitly notes ownership enforcement, which tells users they cannot cancel others' subscriptions. It also clarifies that cancellation is a soft delete, so historical events remain accessible via recent_alerts. However, it does not explicitly name alternatives or state when not to use it, 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?

Beyond the annotations (read-only, open-world, idempotent), the description discloses crucial behavior: the fallback from structured SEC/XBRL to a grounded pipeline, and the precise meaning of ambiguous verdicts like could_not_verify (check didn't happen) vs unsupported (no source found). This is exactly the kind of practical behavioral context an agent needs to correctly interpret results, and it does not contradict 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 longer than average but well-structured: it opens with recognizable trigger phrases, states the use case, explains the two processing paths, lists the verdicts, and clarifies error semantics. Each section earns its place, though the prose could be tightened to reduce redundancy (e.g., the grounded pipeline explanation is repeated).

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 everything needed: the decision logic (which path is taken), the complete set of verdicts, what the return value carries (actual value with citation, reasoning), and how to treat failure cases. It also notes the tool's composability by replacing multiple calls, so the agent understands the full scope and side effects. No significant informational gaps.

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 describes both parameters fully (100% coverage), but the description goes further by explaining the semantics of tolerance_pct in use: how it overrides the claim-wording default, is capped at 5, and should be set to 1–2 for hallucination detection. This adds meaningful guidance beyond the schema's field descriptions.

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

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

The description clearly identifies the tool as a claim-verification utility, with specific verb+resource ('validate claim') and a host of natural-language trigger phrases. It also differentiates from generic research tools by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), making its scope 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?

It explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the two internal paths (SEC fast path for company financials, grounded pipeline for anything else), giving clear context. However, it never mentions when not to use it or names alternative sibling tools, so it lacks explicit exclusion/alternative guidance.

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