Science Feeds

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details: default model is free, BYO key for Anthropic, returns per-model scores and combined view. No contradiction with annotations.

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

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

The description is two sentences long, front-loaded with purpose, and includes essential details without waste. 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?

Despite no output schema, the description explicitly states the return format: per-model {score, confidence, signals, raw_response} + combined view. Parameters are fully explained. No gaps remain.

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 parameter descriptions. The description adds value by providing examples for entity ('Pipeworx', 'OpenInvoice'), listing supported models, explaining the API key purpose, and giving context examples. This enhances understanding beyond the schema.

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

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

The description clearly states it 'probes one or more LLMs for what they know about a business/brand/product/topic and scores visibility'. It specifies the default model and optional Anthropic probing, distinguishing it from siblings like ask_pipeworx which focus on a specific entity.

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 usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the API key. However, it does not explicitly state when not to use or compare to alternatives like scan_competitor_ai_presence.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds context beyond annotations: it routes to internal tools, fills arguments, and returns pipeworx:// citation URIs. It also notes performance characteristics (one fast call, works on every tier), but does not mention potential limitations such as answer freshness or rate limits, which is why it falls short of 5.

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

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

The description is long but every sentence serves a purpose: it front-loads the key 'prefer over web search' message, provides examples, and gives escalation paths. There is no redundant text; the structure logically flows from general purpose to specific usage 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?

Given no output schema, the description compensates by explicitly stating the return format ('structured answer with stable pipeworx:// citation URIs'). It covers when to use, alternatives, and concrete examples, making it self-sufficient 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 fully describes each parameter and alias, with 100% coverage. The description adds examples of valid questions but does not provide any additional parameter-level semantics beyond what the schema already supplies. This meets the baseline for schema coverage.

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

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

The description clearly states the tool's function as a router that answers factual questions by selecting among thousands of tools and returning structured answers with citations. It enumerates specific domains (SEC filings, FDA data, etc.) and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_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 provides explicit 'when to use' with trigger phrases like 'what is', 'look up', and 'find', and a clear 'start here' directive. It also gives alternatives for specific needs: ask_pipeworx_grounded for verbatim evidence and deep_research for broad questions, plus notes on breaking news coverage.

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 the experimental nature, current inactive candidate state, and that it currently matches ask_pipeworx exactly, which goes beyond the annotations' readOnly/idempotent hints. It does not contradict annotations, and though it doesn't dive into routing mechanics, it provides meaningful context about behavior.

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

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

The description is three sentences, each earning its place: what it is, current state, and usage guidance. It is front-loaded with the key phrase 'Beta version of ask_pipeworx' and stays free of fluff, making it exceptionally concise for the information conveyed.

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 rich annotations and full schema coverage, the description is nearly complete. It covers purpose, relationship to stable, usage, and current equivalence, but does not specify return format or potential differences from ask_pipeworx when a candidate is active. Nevertheless, it says 'same response shape' and 'matches ask_pipeworx exactly,' which suffices for current use.

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 all six parameters (question plus five aliases) with full coverage, so the description need not add parameter details. The description does not mention parameters, but per the rubric, full schema coverage sets a baseline of 3, which is appropriate here.

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 'Beta version of ask_pipeworx' and explains it is an identical universal router with the same 5,529 tools and response shape. It distinguishes itself from ask_pipeworx by noting candidate routing improvements and experimental status, making its purpose specific and unambiguous.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It also warns 'Falls back to nothing' to emphasize it is a full working router, not a stubbed beta, giving the agent clear when-to-use context.

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

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

The description adds substantial behavioral detail beyond the annotations: it extracts answers using only tool result content, returns an explicit refusal with a specific refusal_reason enum, and provides evidence as a verbatim quote. It also discloses the additional LLM call cost. This goes far beyond the readOnly/idempotent hints and gives the agent a clear model of tool behavior.

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

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

The description is information-dense and front-loaded with the core purpose. It includes a detailed return structure and refusal reasons, which are valuable but make it somewhat long. Still, every sentence earns its place and the structure is logical. A slightly tighter version could be more concise, but it remains highly readable.

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

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

Despite no output schema, the description fully explains return values and refusal reasons. It also provides context on the underlying routing scale (5,529 tools, 1455 sources) and the trade-off vs ask_pipeworx. For a complex tool with high-stakes use cases, this is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with all aliases documented for the single question parameter. The description adds no parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate for full schema coverage.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by emphasizing extraction using only tool result content and explicit refusal behavior. The verb+resource is specific: provide grounded answers with evidence.

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

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

Explicitly instructs when to use: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. Also specifies when not to use: prefer ask_pipeworx for casual lookups due to the extra LLM call cost. Names the alternative tool 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?

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing extensive behavioral traits: it explains the resolution process, classifier fan-out, safety mechanisms (low-confidence short-circuit), closed market handling, wide spread warnings, and cancellation rule parsing. It also describes the RESOLVER CONTRACT and PARENT_EVENT EXTRACTOR. 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 verbose but front-loaded with the core purpose in the first sentence. It uses headers like RESOLVER CONTRACT and PARENT_EVENT EXTRACTOR to organize complex information. While every sentence adds value, the length could be trimmed without losing essential detail. A slightly more structured summary would improve 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?

Given the absence of an output schema and the tool's complexity (3 parameters, multiple data sources, edge cases), the description is remarkably thorough. It covers the response shape (market, analysis, evidence fields), resolution confidence, parent event extraction, news fallback, safety overrides, illiquid spreads, and cancellation rules. The agent has all necessary context to use the tool correctly and interpret 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?

With 100% schema coverage, baseline is 3. The description adds value by explaining the 'market' parameter can be slug, URL, or text (already in schema), but more importantly details 'depth' with quick vs thorough behavior ('2-3 evidence sources' vs 'full fan-out') and 'include_raw' with size estimates (~20KB vs 50-500KB). These additions help the agent choose parameters 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 clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific resource (Polymarket bet) and action (research via data pull), and distinguishes itself by mentioning the fan-out to multiple data sources in one call. Examples like 'should I bet on X' further clarify its use, setting it apart from sibling tools like polymarket_edge_tracker.

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

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

The description explicitly lists three use cases: 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or directly compare to alternatives like polymarket_arbitrage or deep_research, which would have improved the score.

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

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

The description provides extensive behavioral detail beyond the annotations: for 'company' it specifies it pulls latest 10-K data (revenue, net income, cash, debt) with correct off-calendar fiscal year handling; for 'drug' it pulls FAERS counts, FDA approvals, trial counts. It also notes results are sorted by primary metric and that citation URIs are returned. This fully informs the agent of what to expect without contradicting the readOnlyHint, openWorldHint, or idempotentHint 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 trigger phrases and quickly gets to the purpose. It is comprehensive but slightly verbose in repeating the efficiency gain ('in ONE parallel call' and 'Replaces 8–15 sequential lookups'). Still, every sentence adds value, and the overall structure is logical. Minor improvements could tighten phrasing.

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 has only 2 parameters and no output schema, the description fully explains input expectations, behavior for both entity types, sorting behavior, and output format (paired data + citation URIs). It even covers edge cases like off-calendar fiscal years. An agent has all the information needed to invoke the tool correctly and interpret 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?

The input schema already covers both parameters with descriptions (type enum and values array). The description adds valuable context: examples of values ('AAPL','MSFT' for companies; 'ozempic','mounjaro' for drugs) and constraints (2-5 items). This goes beyond the schema's minimal descriptions, though the schema itself is 100% covered. The added information is helpful but not essential.

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 performs side-by-side comparisons of 2-5 companies or drugs in one call. It provides example trigger phrases ('X vs Y', 'which is bigger') and distinguishes itself from single-entity lookup tools like entity_profile. This makes the purpose unambiguous and easily matched to user intent.

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

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

The description explicitly says to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear guidance on when to use. It does not explicitly list cases when not to use (e.g., single entity), but the context implies it. Alternatives like entity_profile exist for single lookups, and the description indirectly suggests they are inferior for comparisons.

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

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

Annotations already signal safety (readOnly, openWorld, idempotent, non-destructive), but the description adds substantial behavioral context: auth/paid requirements, latency expectations (15-90s), gaps[] behavior, 'never invented', citation_uri only when resolvable, semantic excerpting, contradictions[] for standard/thorough, and hop field. 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 long but every sentence earns its place, covering auth, scope, usage guidance, depth semantics, output format, citation behavior, and performance. Front-loaded with the critical account requirement and alternative. Slightly dense but appropriately organized for a complex tool.

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

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

Given there is no output schema, the description thoroughly explains the return packet: 'verbatim evidence + confidence + source + fetched_at + citation', gaps[], contradictions[], and hop/citation_uri semantics. Also covers latency, edge cases (breaking news), and depth variants, making it fully complete for an agent to predict behavior and outputs.

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

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

Schema covers both parameters at 100%, so baseline is 3. The description adds value by explaining default depth ('standard=5'), that 'thorough' is paid, and how each depth affects behavior (gap recovery, contradictions scan, lead chasing). It also clarifies the 'question' param accepts broad/multi-part questions as decomposition is the point.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and distinguishes it from siblings by explicitly contrasting with ask_pipeworx (single lookup vs. broad/multi-part) and noting it is 'NOT open-web search'. The verb 'research' plus resource scope is precise.

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 and when-not-to-use: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and for breaking/current-news topics prefer ask_pipeworx because deep_research returns empty gaps. Also covers account requirements and fallback if not signed in.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value beyond these by detailing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This provides behavioral insight on output and usability.

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, followed by usage guidance, domain list, return format, and a call-to-action. Every sentence earns its place. While slightly longer than minimal, it remains efficient 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?

Given the 6 parameters (5 aliases for query), no output schema, and 32 sibling tools, the description provides sufficient context: it explains when to use it (first step for discovery), what it returns (tools with schemas), and aliases for query. It does not explain error cases or empty query handling, but the required parameter mitigates that 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 all 6 parameters described. The description adds context about alias behavior: 'Accepts task, q, description, search as aliases.' It also notes defaults and limits for 'limit' parameter. This adds meaningful value beyond the schema's own parameter 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's purpose with a specific verb 'Find tools' and resource 'by describing the data or task'. It lists supported domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set'.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. It implies when not to use it (when you already know the exact tool), but does not provide explicit exclusions.

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

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

Annotations already mark readOnlyHint=true, openWorldHint=true, etc. Description adds behavioral details: parallel fan-out across multiple sources, soft-fail for patents, and the exact output fields. 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 well-structured with example queries upfront and a detailed breakdown of returns. While verbose, each sentence adds value. Minor conciseness improvements possible.

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 (multi-source profile), schema simplicity (2 params, enum), and no output schema, the description is remarkably thorough, covering sources, current limitations, and precise outputs.

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. Description adds context: type is 'company' only, value can be ticker or CIK, and names are unsupported, enhancing clarity beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and fields returned. It distinguishes from alternatives by recommending preference over 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?

Explicitly provides example queries ('Tell me about X', 'research Acme'), states when to prefer this tool ('ALWAYS PREFER over chaining'), and clarifies when not to use ('names not supported – use resolve_entity first').

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, non-destructive. Description adds useful context: CF-robust with direct fetch and proxy fallback, and normalization. No contradiction with annotations.

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

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

Two sentences, each serving a distinct purpose: first defines core action, second adds robustness and usage guidance. 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?

Tool has no output schema; description does not explain return format. However, it does specify normalization and gives examples in schema. For a fetch tool, mostly complete, but lacks explicit return value description.

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

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

Schema covers 100% of parameters with clear descriptions. Description does not add extra meaning beyond schema, but also does not mislead. Baseline score for full schema coverage.

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

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

Description clearly states verb ('Fetch and normalize'), resource ('any RSS / Atom / RDF feed'), and parameter ('by URL'). It also distinguishes from sibling 'list_feeds' by advising to use that 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?

Explicitly guides to use 'list_feeds' first for curated sources, providing a clear alternative. Also mentions CF-robust fallback behavior, but does not give explicit exclusions or prerequisites.

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

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

Annotations already indicate destructiveHint=true. The description says 'delete', which is consistent. No additional behavioral details 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?

Two sentences: first states purpose, second gives usage context. No unnecessary words, front-loaded with action.

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 single parameter and no output schema, the description is fully adequate. It covers what the tool does and when to use it.

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

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

Schema description coverage is 100%, and the schema already describes the 'key' parameter as 'Memory key to delete'. The description says 'by key' but adds no extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory). It implicitly distinguishes from sibling tools like remember and recall by mentioning them.

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 scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. Does not state when not to use, but the context is clear.

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

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

Annotations already declare read-only, idempotent, not destructive. Description adds specifics: fetches the page, extracts title/description/key links, emits standard format, and returns a single text blob. 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 purpose. Every word adds value: specifies input, output, format, and use cases. 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?

All parameter semantics covered, return value explained as a text blob (no output schema needed). Use cases provided. For a simple tool with rich annotations, the description is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds extra context: max_links default is 25 with max 50, which is beyond the schema. Baseline 3 plus additional info justifies 4.

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

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

Description clearly states the tool generates an llms.txt file for any URL, extracting title/description/key links and emitting standard markdown. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by specifying the output format and use case.

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 lists three use cases: getting a client's site indexed, drafting for your own project, auditing competitors. No explicit exclusions of when not to use, but the context is sufficiently clear for an AI agent.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about the returned fields and filtering, without contradicting annotations.

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

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

The description is two short, front-loaded sentences with no redundant information. Every sentence adds value.

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

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

For a simple list tool with no output schema, the description covers the action, output fields, optional filters, and links to a related tool. Fully 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?

Schema coverage is 100% with descriptions for both parameters. The description adds little beyond restating the filtering options; 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 states the tool lists curated science & space feeds with specific fields (id, title, category, source). It distinguishes from sibling 'read_feed' by saying 'Pass an id to 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 usage context: optionally filter by category or keyword, and hints at the alternative tool read_feed. However, it does not explicitly state when not to use this tool or provide other alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by listing the return fields (id, type, params, etc.) and explaining the effect of the 'include_inactive' parameter. This enriches the agent's understanding 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?

Two sentences: first states the action and return fields, second provides usage advice. No redundancy, every sentence earns its place.

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

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

Despite having no output schema, the description lists the return fields. It also explains the single parameter's default behavior. For a simple tool with good annotations and schema coverage, the description is complete enough for effective use.

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

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

The schema has 100% description coverage for the single parameter ('include_inactive'), so the description does not add new semantics. It implicitly references the parameter by mentioning 'active subscriptions' but does not provide additional meaning.

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

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

The description clearly states it lists the caller's active subscriptions, specifying the action ('list'), the resource ('subscriptions'), and the scope ('caller's active'). It distinguishes from siblings like 'subscribe' and 'unsubscribe' by stating its purpose as a review 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 description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use guidance and implying when not to use (e.g., when you need to create or delete subscriptions).

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

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

Annotations are all false, so the description carries the full behavioral burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), free usage, the claim_token round-trip, and the fact that the team reads digests daily. These go well beyond annotations and set accurate agent 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 longer than typical but every sentence adds unique information: purpose, when to use, exclusions, claim_token mechanics, rate limits, and roadmap impact. It is front-loaded with the primary purpose and organized logically, so no sentence is wasted.

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

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

The description completely covers the tool's operation: what it does, when to use it, what to include, what to expect in return (claim_token), and limitations. Since there is no output schema, the explanation of the claim_token flow is essential and provided clearly.

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 adds value beyond the schema by giving a concrete usage example for the claim_token parameter ('pipeworx_feedback({claim_token:"pwfb_…"})') and by clarifying message content ('don't paste the end-user's prompt'). This justifies a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies feedback categories (bug, feature/data_gap, praise) and distinguishes this tool from all sibling tools, which are research/feed-related.

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

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

It explicitly states when to use the tool ('Use when a tool returns wrong/stale data', etc.) and when not to ('if the tool came from a different MCP server... file it with that server instead'). This provides clear inclusion and exclusion criteria, plus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details beyond annotations: the data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This provides useful transparency about data source and freshness.

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

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

The description is moderately concise with three clear parts: what it returns, three use cases, and key properties. Every sentence adds value, though the second sentence about caching could be slightly shortened. Front-loaded with the main result.

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 has one optional parameter, no output schema, and rich annotations, the description is complete. It covers output components, use cases, data source, privacy, and caching. No gaps remain for correct 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?

With schema description coverage at 100%, the baseline is 3. The description adds meaning by explaining the purpose of different windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the parameter semantics beyond the schema's enum 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 tool returns 'top tools, top packs, and total call volume over a recent window' with a specific verb 'returns' and resource 'trending data on Pipeworx'. It distinguishes from sibling tools like 'discover_tools' by focusing on trend discovery rather than tool listing.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment). While it does not explicitly state when not to use or name alternatives, the use cases are clear and actionable. The sibling tool list provides context for alternative choices.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses internal logic (semantic anchor, partition filter, fill check against CLOB depth), response structure, and limitations (skipped_low_similarity, placeholder filtering). 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 thorough and well-organized, starting with overall purpose, then detailing each mode, followed by additional checks and response. While lengthy, every sentence adds value; could be slightly more concise but remains clear.

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 (arbitrage detection, multiple modes, no output schema), the description covers all necessary aspects: parameters, modes, internal checks, response structure, and fill risk. It provides sufficient information for an agent to understand and use the tool correctly.

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

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

Schema covers parameters 100%, but the description adds significant value by explaining the meaning of event slugs and topic seed questions, providing examples, and detailing behavioral differences between modes. Accepting full URLs is also noted.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by specifying its unique methodology and also mentions alternative tools for custom sizing.

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

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

Provides explicit guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event scan) and recommends event mode for specific markets. It also explains when not to trade (if realizable_edge_pp <= 0) and directs 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?

The description fully aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) and adds extensive detail about internal logic, model families, edge calculation, caching, and diagnostic output. No contradictions; it provides transparency beyond what annotations offer.

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 lengthy but well-structured with clear sections and front-loaded main purpose. Every sentence adds value, explaining complex details. While concise for the complexity, it could be slightly trimmed without losing clarity.

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

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

Despite no output schema, the description thoroughly explains the response structure, including by_segment, fed_candidates, and diagnostics. It covers edge cases like empty segments and provides caching details. For a complex tool with 9 parameters, the description is remarkably complete.

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

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

All 9 parameters are described in the schema (100% coverage), so baseline is 3. The description adds meaningful context, such as explaining the rationale behind slippage_pp (Polymarket fees) and the purpose of min_partition_leg_kelly for partition arbs. This extra value justifies a 4.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the tool is for discovering betting opportunities, distinguishing it from siblings like polymarket_arbitrage or polymarket_edge_tracker by detailing its unique model families and data 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 explicitly says 'Built for 'what should I bet on today'', giving a clear use case. It describes when to use it and mentions tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or directly compare it to alternatives like polymarket_arbitrage, though the unique features imply differentiation.

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

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

Annotations confirm read-only, idempotent, non-destructive. Description adds rich behavioral details: 60-day TTL, snapshot gaps, decay from daily closes, response structure with tracked/expired/snapshot_dates. 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?

Front-loaded with purpose and key analogy. Response format explained thoroughly but efficiently. Slightly long but every sentence provides value. Well-organized.

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

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

Given no output schema, description fully explains response fields (tracked, expired, snapshot_dates) with field details. Mentions limitations (TTL, snapshot gaps, decay from closes). Complete for an AI agent to use correctly.

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

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

Schema covers both parameters (100% coverage). Description adds context: defaults (14 days, 1wk), clamp (2-30), and meaning of window as 'snapshot family'. Adds value beyond schema.

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

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

Description clearly states tool provides edge persistence and decay telemetry from daily snapshots, with a specific question it answers. It distinguishes itself from siblings like polymarket_edges by 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?

Explicitly tells when to use (check how long an edge has existed) and contrasts fresh vs aged edges. Implicitly differentiates from polymarket_edges but does not 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 indicate the tool is read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral details: it walks the live order-book ladder, returns specific fields (slippage, fill details, verdict), and warns that partial basket fills convert an arb into an unhedged directional position, which is the dominant loss mode. No contradiction with annotations.

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

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

The description is lengthy but well-organized with clear sections for SINGLE-MARKET and BASKET modes, and each sentence provides necessary details. It could be slightly more concise, but the structure aids readability and completeness.

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 (two modes, multiple parameters, important behavioral insights) and absence of an output schema, the description covers all key aspects: inputs, return fields, usage context, and risks. It fully equips an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that market or event is required (mutually exclusive), clarifies default side behavior in basket mode ('auto from partition sum'), and interprets size_usd differently for buys vs sells and for basket mode (settlement notional). This goes 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 defines the tool as a 'realizable-vs-theoretical edge check' against live order-book depth. It distinguishes between single-market and basket modes, each with specific behavior and return values, effectively differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use the tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the rationale (theoretical overround not capturable, partial basket fills create unhedged positions) and provides clear directional context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds extensive behavioral context: two modes, response format with safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and explanations of when matches are invalid. This far exceeds 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 long but well-structured with bold headings, bullet-like explanations, and a logical flow. Every sentence adds value, but it could be slightly more concise without losing clarity.

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

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

Despite no output schema, the description thoroughly covers the response structure (leg-by-leg prices, top spreads, safety fields like compatibility_warning and temporal_alignment). It also explains edge cases such as shape incompatibility and temporal misalignment, making it complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the two modes, giving example tickers, and listing the 10 pre-mapped shortcuts. This provides context beyond the schema comments.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on spread rather than arbitrage and provides specific modes.

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 explains two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings. It also explains safety fields that indicate when spreads are invalid. However, it does not explicitly compare to sibling tools or give when-not-to-use advice beyond the warnings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety traits. It adds value by specifying the return structure (normalized items) and optional filtering. 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 sentences deliver all necessary information: purpose, prerequisite, output format, and optional filtering. No redundant words, and the key information 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 read-only tool with comprehensive annotations and parameter schema, the description provides sufficient context: how to get the feed ID, what the tool returns, and filtering capability. No output schema exists, but the description adequately explains the return format.

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

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

Input schema has 100% description coverage for all three parameters. The description adds limited extra meaning, only contextualizing the feed ID source ('from list_feeds'). Since the schema already documents parameters well, the description earns a 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 clearly states the action ('Read'), the resource ('a curated science & space feed by its id'), and the output ('Returns normalized items (title, link, published, summary)'). It distinguishes from sibling tools like 'list_feeds' and 'fetch_feed' by emphasizing curation and the need for an ID from list_feeds.

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 context by linking to 'list_feeds' for obtaining the feed ID, and mentions optional keyword filtering. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'fetch_feed' for non-curated feeds) or provide exclusions.

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

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

Annotations already declare read-only and idempotent. Description adds scope details (identifier-based isolation) and listing 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?

Two efficient sentences front-loading main purpose. No fluff, every sentence adds value.

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

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

For a simple read tool with one optional parameter and no output schema, description fully explains behavior, scope, and related tools. No 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?

Schema coverage is 100%, description reiterates schema meaning (key to retrieve or omit to list). Adds no new semantic detail beyond what schema 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?

Description clearly states the tool retrieves a value saved via remember, or lists all keys when key omitted. It specifies the resource and action, and distinguishes from siblings remember and forget.

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 case: looking up context stored earlier without re-deriving. Mentions pairing with remember/forget. Could include more explicit when-not-to-use, but overall clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable detail: what events carry (source, citation_uri, payload), the effect of mark_read, and the existence of an alternative feed URL. 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?

Three well-structured sentences, each serving a purpose: stating the action, listing returned fields and filter options, and noting mark_read behavior and alternative access. No waste.

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 5 optional parameters and no output schema, the description sufficiently covers return fields, filtering, and mark_read semantics. It also provides alternative retrieval method (URL). No 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning to parameters: 'type' filter, 'since' ISO timestamp, 'mark_read:true' flags events read, and 'unread_only'. 'limit' is not elaborated, but schema mentions default. Overall adds value beyond schema.

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

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

The description starts with 'Pull fired events from your subscription feed', a specific verb-resource pair. It clearly distinguishes from siblings like 'read_feed' and 'fetch_feed' by focusing on 'recent alerts' and mentioning an alternative URL for scripts/dashboards.

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 'Polls work fine' and gives an alternative URL for scripts/dashboards, providing context. However, it does not explicitly contrast with siblings or specify when not to use this tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the tool's behavior: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and returns structured changes with citation URIs. This adds significant 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 a single, front-loaded paragraph with no wasted sentences. While it is dense, it efficiently conveys all needed information for a complex tool.

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

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

Given the tool's multi-source complexity, lack of output schema, and many siblings, the description covers all essential aspects: sources, fallbacks, return structure, and differentiation from siblings. No 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?

Schema coverage is 100%, but the description adds value by explaining 'since' with examples (ISO date and relative shorthand) and clarifying that 'type' only supports 'company'. This goes beyond the schema descriptions.

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

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

The description specifies the tool's purpose with clear verb+resource: 'change feed for a company in the last N days/weeks/months'. It provides example queries and distinguishes from 'entity_profile', a sibling tool for static profiles.

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 this tool vs. alternatives: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior and limitations, providing clear 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 idempotentHint=true and destructiveHint=false. The description adds context about scope ('scoped by your identifier'), expiration (24 hours for anonymous), and pairing with recall/forget, which goes 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?

Multiple sentences but each adds value. Front-loaded with purpose. No redundant information. Could be slightly more concise, but structure (purpose, usage, mechanics, pairing) is logical.

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, but for a write tool this is acceptable. Covers purpose, usage, persistence, and pairing with siblings. Adequately complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions. The description adds value by giving example keys ('subject_property', 'target_ticker') and clarifying value semantics ('any text'), enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose ('Save data the agent will need to reuse later') and resource ('key-value pair'). It distinguishes itself from sibling tools like recall and forget by explicitly pairing with them.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward'), references alternatives (recall, forget), and notes authentication-based persistence differences.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit handling of unresolved identifiers. This provides valuable operational context and behavior.

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

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

The description is long but front-loaded with common user phrasings and a clear purpose. Each supported type has necessary detail, and every sentence carries information. Slightly verbose but justified by 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 description fully accounts for behavior: supported types, input/output details, fallback behavior, and internal cascading. Since no output schema exists, the description provides enough return-value information to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds accepted input forms (ticker, CIK, name for company; brand/generic for drug) and explains output structure including source-labelled identifiers and `unresolved` field. This supplements the schema meaningfully.

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 resolves user-spoken names to canonical/official identifiers needed by other tools, using specific verbs ('resolve', 'look up') and resource ('entity'). It distinguishes from siblings by emphasizing the name-to-ID conversion, unlike entity_profile or compare_entities.

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also lists supported types and input formats. However, it does not explicitly name alternative tools or conditions when not to use it, so it lacks full when-not/alternatives coverage.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. No contradiction with annotations.

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

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

Two concise sentences. First sentence defines the core function; second adds a use case and output details. No redundancy, front-loaded with key action.

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 4 parameters (all documented in schema), no output schema, and no nested objects, the description covers the tool's purpose, process, and return characteristics (ranked list with score, confidence, signal density). It is sufficient for an agent to select and 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 coverage is 100%, baseline 3. The description adds value by explaining the 'entities' parameter: first entry is the subject, rest competitors. It also notes 'context' disambiguates common names, enriching semantic understanding beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'probes', 'ranks', and 'surfaces'. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility and ranking.

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 concrete use case: competitive AI-marketing audits, with an example question. It implies when to use (for comparisons) and hints at alternatives (single-entity check via ai_visibility_check), though it could be more explicit about when not to use or specify alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant context: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed listed, and details the return structure (summary block, advisories, links, alternatives). No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then details the output, use cases, and caveats. Every sentence is meaningful and well-structured, earning its place without redundancy.

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

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

Given the complexity of the tool (multiple data sources, no output schema), the description covers output fields, behavior on failure, and ecosystem scope. It is sufficiently detailed for an agent to understand what the tool returns and how to use it.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description mentions scoped packages and default version, but these are already in the schema. No additional semantic 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?

Description clearly states a composite check for adding npm packages, specifying the verb 'check' and the resource 'npm package'. It distinguishes from siblings by focusing on npm ecosystem and providing a unique combined scan of deps.dev and bundlephobia.

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: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. Also gives a when-not: only for npm ecosystem v1, with alternatives for other ecosystems (deps.dev:version).

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 idempotent, read-only, non-destructive. Description adds specifics: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag. 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 concise sentences: first states purpose and key benefit (saves context, returns offsets), second provides technical details. 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?

Despite no output schema, description explains return format (passages with offsets and similarity scores), entity sizes, and pairing with sibling. Complete for effective use.

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 description adds context: text max 200K chars, query examples, limit default 5 and range 1-20. This enriches parameter understanding beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the use case (record too large for context). It distinguishes from sibling tools like ask_pipeworx_grounded by noting pairing strategy.

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 advises when to use: 'when the record is too big to cram into the prompt'. Pairs with ask_pipeworx_grounded for grounding over relevant passages. No ambiguity.

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

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

Annotations already provide idempotentHint and non-destructive, but description adds critical context: OAuth requirement, delivery channels with HMAC signing, auto-disable after 10 failures, and return value. Goes well 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?

The description is long but well-structured, front-loading the main purpose and then detailing types and delivery. Every sentence adds value; could be slightly more concise but still effective.

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

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

For a complex tool with multiple subscription types and delivery channels, the description covers prerequisites (OAuth), return value, type parameters, delivery constraints, and failure behavior. No output schema, so description fulfills the need comprehensively.

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

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

Schema coverage is 100%, so parameters have descriptions. However, the description adds substantial value by explaining type-specific parameters with examples and clarifying delivery options, including constraints not in 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id'. It distinguishes from siblings like list_subscriptions and unsubscribe 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?

Explicitly requires Pipeworx OAuth account and details delivery constraints (phone verification, 10/day cap). Provides context on supported types and parameters, but does not explicitly state when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds context: returns category-bucketed example questions with exact tool+argument shapes, and mentions it draws from a live catalog of thousands of tools. 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 comprehensive but slightly long. It is well-structured with categories and usage instructions. Every sentence adds value, but could be trimmed slightly for brevity.

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 role as an onboarding entry point, the description fully covers what it returns (category-bucketed questions with tool shapes), when to use it (first interaction), and optional topic filtering. No output schema needed; return format is explained.

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% (one parameter fully described). Description adds that topic is optional, lists example values, and explains that omitting it gives a cross-category spread. This adds useful context 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 it is the onboarding entry point, returns category-bucketed example questions, and can be filtered by topic. It distinguishes from siblings like ask_pipeworx by specifying 'Use this FIRST when you do not yet know what Pipeworx can do'.

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 says 'Use this FIRST' and describes optional topic filtering. While it does not provide explicit when-not scenarios, the context from sibling names implies alternatives. Clear guidance for initial 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds that the row is deactivated not deleted and historical events remain via recent_alerts. This provides value beyond annotations, though the readOnlyHint=false is already implied by 'cancel'.

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. First sentence states the purpose concisely. Second sentence adds essential behavioral context. No redundant information.

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

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

No output schema is provided, so the description should ideally mention the return value or success indication. The description references recent_alerts for historical events, which is useful, but omits error handling or confirmation behavior.

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

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

Schema coverage is 100% with id described as 'Subscription id (uuid) returned by subscribe.' The description adds context by stating 'by id' and ownership, but does not significantly extend meaning beyond the schema.

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

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

The description states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific, and the sibling tools 'subscribe' and 'list_subscriptions' provide clear differentiation.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context. It does not explicitly exclude scenarios or name alternatives, but the context is sufficient for an agent to decide.

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/idempotent annotations, the description discloses crucial behavior: two-tier routing, return verdicts, and the important semantic distinction between could_not_verify (check did not happen) and unsupported (no source). This directly prevents misuse of inconclusive 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 front-loaded with trigger phrases and purpose, then covers routing, returns, and critical caveats in a logical order. Despite its length, every sentence carries necessary information for safe invocation.

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

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

Since there is no output schema, the description fully explains return values (verdict enum, evidence with citation, reasoning) and error semantics (could_not_verify vs unsupported). It also covers scope, routing, and parameter context, making it complete for a complex tool.

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

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

Schema covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds context about percent-delta math and tolerance behavior, but the schema already documents these; no significant new parameter meaning is added.

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 natural-language claim verification tool with specific trigger phrases and a verdict output. It distinguishes itself from sibling research/entity tools by focusing on true/false verification and even notes it replaces a multi-step pipeline.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the internal routing between SEC EDGAR and the grounded pipeline. It mentions replacing 4-6 sequential calls, but does not name sibling tools or explicitly state when not to use it.

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