Uk Ons

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by detailing the default model, API key handling for Anthropic (BYO key, direct payment), and return structure (per-model score, confidence, signals, raw_response + combined view). 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 a single paragraph, front-loading key info (what it does, default model, API key note). Every sentence adds value 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 4 parameters and no output schema, the description covers inputs, behavior, return structure, and use cases. No obvious gaps for an AI agent to use this tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about the default model being free, and explains when _apiKey is needed. This enhances understanding beyond the structured field.

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 LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. It specifies the default model and optional Anthropic probe, distinguishing it from sibling tools like ask_pipeworx or deep_research which serve different purposes.

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 mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not provide when-not-to-use or direct comparison to siblings, but the context is clear enough.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses that the tool can be slow or fail if it tries too many sub-queries or picks the wrong source. It also explains that results are returned as stable pipeworx:// citation URIs and warns not to fetch citation links, which is non-obvious behavioral context. There is no contradiction with the annotations.

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

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

The description is useful but bloated and repetitive: "START HERE for most questions" appears twice, and generic execution instructions about not retrying errors and running tools in parallel are mixed in with tool-specific routing guidance. It is front-loaded with the most important preference, but not concise or tightly structured enough to earn every sentence 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?

For a read-only routing tool with one real required parameter, the description covers triggers, examples, output format, failure modes, fallbacks, citation handling, ambiguity handling, and even entity disambiguation via resolve_entity. No output schema is necessary because the description explains what the structured answer and citation URIs look like, and the schema fully documents the input.

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

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

Schema coverage is 100%, and every parameter is an alias for the natural-language question; the schema already documents this thoroughly. The description adds useful examples and a best-guess interpretation rule, but it does not materially extend parameter meaning beyond what the input schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a clear directive to prefer this tool over web search for current or historical data, then states it routes the question to the right of 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. This names a specific action, resource, and output, and clearly distinguishes it from generic web search and 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?

The description explicitly lists trigger phrases such as "what is", "look up", "find", "get the latest", and "current", with concrete examples. It also names alternatives and fallback conditions: ask_pipeworx_grounded for hallucination control, ask_pipeworx_beta for updated routing, and deep_research for multi-part or broad questions. This is explicit when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses live candidate routing behavior, the current inactive state with exact parity to ask_pipeworx, and the no-fallback nature ('this IS a full working router'). This is meaningful operational context that helps an agent set expectations.

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

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

The description is dense but front-loaded with the core identity and current state, then provides supporting details. The retired-candidate date adds slight granularity, but it supports the claim that the tool currently matches ask_pipeworx exactly.

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?

It covers current parity, experimental status, fallback behavior, and response-shape sameness. It does not enumerate the 5,798 tools or detail the response format, but those are delegated to ask_pipeworx and the input schema, which is reasonable for this tool.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and aliases. The description only says 'same arguments' without adding parameter-specific meaning, which is acceptable given the 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 identifies this as the beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It also distinguishes it from the stable sibling by highlighting the experimental routing-improvement angle, so an agent can tell it apart from ask_pipeworx.

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

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

It explicitly says to use it like ask_pipeworx when you want the newest routing, and it references comparison against the stable router. It lacks an explicit when-not or a direct 'use ask_pipeworx for stable/production' exclusion, 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?

The description discloses detailed behavior beyond the readOnly/idempotent annotations: it explains the extra LLM call cost, the exact success return shape with evidence and confidence, and the enumerated refusal reasons. Since there is no output schema, this is essential context and it is fully provided.

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 defining characteristic, then covers behavior, return contract, use cases, cost trade-off, and alternative preference in a logical order. The length is justified by the complexity of the tool, and every sentence carries operational 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?

The definition is complete for invocation decisions: it explains routing behavior, grounded extraction constraints, response and refusal shapes, when to use it, when not to use it, and the extra cost. No critical operational detail is missing.

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

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

Schema description coverage is 100% and all parameters are aliases for the same 'question' field, so the schema already fully documents the inputs. The description focuses on usage context rather than adding parameter-level semantics, which is acceptable but does not elevate the score.

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

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

The description states a specific mode: 'Hallucination-resistant answer mode for high-stakes reads', and explains that it extracts the answer using only the tool result content. It clearly differentiates itself from ask_pipeworx by emphasizing the grounded, evidence-citing behavior.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' with concrete high-stakes examples. It also names the alternative ask_pipeworx and says to prefer it for casual lookups, making the selection criterion 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?

The description adds significant behavioral context beyond annotations: resolution confidence levels, parent event extraction, fallback mechanisms in news fields, safety checks for low-confidence matches, handling of closed markets, wide spread warnings, and cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and the description enriches them.

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

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

The description is comprehensive but overly verbose, running several paragraphs with intricate details like fan-out examples and response shapes. While front-loaded with the core purpose, it could be more concise and structured for quick consumption. Some sentences are dense and may overwhelm an agent.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers inputs, classification, fan-out logic, response fields, resolver contract, parent event extraction, news fields with error handling, safety states, and resolution rules. It leaves no significant gaps for an agent to misunderstand usage or 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% and the description adds value by explaining the market parameter's flexibility (slug, URL, text) and the depth parameter's behavior ('quick = 2-3 evidence sources, thorough = full fan-out'). It clarifies the include_raw parameter's impact on response size, which goes beyond the schema's basic type info.

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 specifies the input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison), distinguishing it from siblings focused on other tasks like arbitrage or edge tracking.

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 provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives extensive examples for different bet categories, but lacks explicit guidance on when not to use this tool versus alternatives like polymarket_edges or deep_research.

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

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

Description adds significant context beyond annotations: off-calendar fiscal year handling, specific financial fields for companies, drug-related counts, sorting by metric, and citation URIs. Annotations already indicate read-only, idempotent, non-destructive, open-world; description enriches this without contradiction.

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

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

Description is compact (5 sentences), front-loaded with trigger phrases, and every sentence adds unique value. No redundancy or fluff.

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

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

Covers key aspects: entity types, data sources, sorting, citation format, and efficiency relative to alternatives. Without output schema, it mentions return structure (paired data + URIs). Missing details on error handling or edge cases, but acceptable for a comparison tool.

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

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

Schema coverage is 100% with both parameters described. Description provides concrete examples (tickers/CIKs for company, drug names) and clarifies constraints (2-5 items). This adds value beyond the schema's property descriptions.

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

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

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs, lists trigger phrases, and distinguishes between entity types with specific data sources (SEC EDGAR for companies, FAERS/FDA/trials for drugs). It contrasts with sequential single-entity lookups, making purpose unambiguous.

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

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

Explicitly instructs to prefer this tool over sequential lookups when comparing entities, and provides example queries. Does not explicitly state when not to use (e.g., single entity), but this is easily inferred from 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?

Discloses substantial behavior beyond annotations: account requirements, depth tiers, parallel decomposition, findings packet fields, gaps[], contradictions[], citation resolvability, semantic excerpting, and expected latency. No contradiction with readOnlyHint/openWorldHint/idempotentHint/destructiveHint.

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

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

Long but well-structured and front-loaded with gating/access info before purpose and behavior. Each section adds actionable details; the length is justified by the tool's complexity, though it could be trimmed slightly without losing critical 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?

With no output schema, the description fully explains what the agent should expect: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and timing. Nothing essential is missing for correct invocation and interpretation.

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 meaningful nuance by explaining how each depth value behaves (quick=3 facets, standard adds gap recovery, thorough adds paid iterative chase) and clarifies that the question can be broad/multi-part. This exceeds baseline without being necessary for basic invocation.

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

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

Description states a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call. It explicitly distinguishes this from open-web search and from the sibling ask_pipeworx for single 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?

Explicit guidance is given for when to use this tool: broad/multi-part questions over structured data. It also says to use ask_pipeworx for single lookups and if the user is not signed in, making the selection decision 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 declare readOnlyHint=true and destructiveHint=false, which the description aligns with. The description adds valuable behavioral details: returns top-N relevant tools with full schemas and curated examples, ready to call without a second lookup. 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?

Description is front-loaded with purpose, followed by a specific list of data domains, then return details and usage advice. It is slightly wordy but each sentence adds value. The list of domains could be trimmed, but overall efficient for the tool's complexity.

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

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

Given the tool's role as a discovery gateway with multiple parameter aliases and no output schema, the description covers: what it does, when to use, what it returns (top-N tools with schemas and examples), and parameter aliases. It is fully adequate 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%, so baseline is 3. The description adds value by clarifying that 'query' is the primary parameter and listing its aliases (task, q, description, search), which the schema notes but the description reinforces. It also provides example queries and a default limit of 20 (max 50).

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a discovery mechanism, supported by the instruction to 'Call this FIRST' when many tools are available.

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 calling this tool first when exploring available tools: 'Call this FIRST when you have many tools available.' It implies this is for browsing/discovery, not for invoking a known tool. While no alternative tools are named, the usage 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 readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond this by disclosing important behavioral traits: the patent source soft-fails after May 2025, empty sections (like fda_products for small-molecule-only companies) are expected rather than bugs, private companies return resolved:false with an explicit notes line, and sources_used/sources_failed indicate real data absence. This richly supplements the annotation coverage and adds 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 long but every sentence carries actionable information, covering input forms, output fields, failure modes, and edge cases. The core purpose is front-loaded in the first sentence, then details expand logically. It could be slightly more structured (e.g., bullet points), but for a tool this complex, the density is justified and not wasteful.

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

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

Given the tool's complexity (multiple data sources, many output fields, no output schema), the description is exceptionally complete. It enumerates all returned sections (cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), explains the semantics of sources_used/sources_failed, covers edge cases (private companies, patent sunset), and describes the output URIs. Nothing an agent needs to call it correctly or interpret results is missing.

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

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

Schema coverage is 100% and both parameters are described, but the description adds significant semantic value beyond the schema: it clarifies that 'type' accepts 'company' or 'ticker' interchangeably, that 'value' can be a ticker, CIK, or company name, and explains the resolution behavior for names (via SEC EDGAR company-name match). This goes beyond what the schema states, providing crucial disambiguation for callers.

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

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

The description opens with a clear verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It immediately distinguishes itself from chaining single-pack lookups and from sibling tools like compare_entities, deep_research, and resolve_entity by emphasizing the holistic, one-call nature. The included example phrasings ('Tell me about X', 'research Acme') make the trigger conditions unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear when-to-use directive. It also notes name resolution behavior, which helps differentiate from resolve_entity. However, it doesn't explicitly name sibling tools as alternatives or state explicit 'do not use' conditions for specific cases, so it stops short of a 5 but is strong.

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

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

Annotations indicate destructiveHint=true, and the description confirms deletion. It adds useful context about why to delete (stale, done, sensitive data) 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 with no fluff. First sentence states the action, second provides usage guidance and related tools. 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?

For a simple tool with one required parameter and no output schema, the description fully covers what the tool does, when to use it, and how it relates to other tools.

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

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

Schema coverage is 100% with a clear description for the `key` parameter. The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description explicitly states 'Delete a previously stored memory by key.' It uses a specific verb and resource, and distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

The description provides clear usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It does not explicitly state when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds value by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which provides process details beyond annotations. 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 three sentences long, front-loaded with the purpose, followed by the process and use cases. Every sentence earns its place with no redundancy or fluff. Highly efficient.

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

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

Given 2 parameters with 100% schema coverage, rich annotations, and no output schema, the description explains the output as 'a single text blob ready to drop at site-root/llms.txt' in standard format. It omits error handling or edge cases but is sufficient for a simple generation tool. Slightly more detail on output format constraints would push to 5.

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

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

Schema descriptions cover 100% of parameters, including 'url' and 'max_links' with details. The main description doesn't add new parameter-level meaning beyond the schema, but it does contextualize them by mentioning the default and max for 'max_links' (though schema already has default). Baseline 3 is appropriate as the description neither compensates for deficiencies nor adds substantial value.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the context. It distinguishes itself from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on file creation rather than analysis or scanning.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It could be improved by specifying when not to use this tool versus alternatives, but the given scenarios are clear and helpful.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context about the returned metadata fields but does not disclose additional behavioral traits beyond what annotations provide.

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

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

The description is extremely concise, using a single sentence with no wasted words. It front-loads the key information about what the tool returns.

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

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

Given the tool's simplicity (1 parameter, output schema present), the description adequately covers the returned metadata fields. No further context is needed.

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

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

The input schema has 100% documentation coverage for the single parameter dataset_id, including examples. The description does not add extra meaning beyond the schema, so it meets the baseline.

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

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

The description clearly states it returns 'Single dataset metadata' and lists specific attributes (title, description, methodology, etc.). It effectively distinguishes from sibling tools like list_datasets and ons_timeseries by focusing on a single dataset's metadata.

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 does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for obtaining metadata for a specific dataset but lacks exclusion criteria or mention of other tools for different needs.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so description adds no new behavioral traits. The description is consistent but does not disclose potential limits or auth requirements.

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 purpose, no unnecessary 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?

Covers essential usage for a data-fetching tool. Does not explain error handling or output format (output schema exists), but is adequate for the complexity.

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

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

Schema coverage is 100%, but description adds meaning by explaining the map format for 'dimensions' and the wildcard usage, complementing the schema.

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

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

The description uses specific verb+resource ('Fetch observations from a dataset/edition/version') and distinguishes from sibling tools like 'get_dataset' and 'get_version' by focusing on data retrieval with dimension filters.

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

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

Provides clear instructions for passing dimension filters and using '*' for all values. Does not explicitly state when to use vs. alternatives, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool fetches metadata with specific fields, which does not contradict annotations but also does not significantly enhance behavioral transparency beyond what annotations provide.

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

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

The description is a single concise sentence that efficiently lists the return contents. No extraneous 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?

Given the tool has a clear purpose, comprehensive annotations, and an output schema (not shown but exists), the description is complete. It covers what the tool does and what it returns, leaving no obvious 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% with brief descriptions. The description does not add any additional parameter semantics beyond what is in the schema. Baseline score of 3 is appropriate since the schema already covers the parameters.

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

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

The description clearly states the verb 'Fetch' and the resource 'metadata for a specific version of an ONS dataset edition', listing included elements. This differentiates it from siblings like 'get_dataset' (which likely fetches dataset-level metadata) and 'list_editions'.

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 use when you need metadata for a specific version, but does not explicitly state when not to use it or suggest alternatives. Given the sibling tools list includes 'get_observations' and 'list_editions', some guidance on scope would help.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, non-destructive read operation. The description adds that the tool is paginated, which is consistent and useful context 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 a single sentence that front-loads the key feature (paginated catalog) and lists return fields succinctly. Every word serves a purpose with no redundancy.

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

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

Given the tool's simplicity (2 optional params, output schema exists), the description fully covers purpose, return format, and pagination. No gaps remain for an agent to invoke correctly.

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

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

Schema coverage is 100% with both 'limit' and 'offset' having descriptions. The description does not add extra meaning beyond what is in the schema; it only mentions 'paginated' which aligns with the parameters. Baseline score of 3 is appropriate.

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

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

The description clearly states it is a paginated catalog of ONS datasets and lists the specific fields returned (id, title, description, contacts, release frequency, last release, theme). It distinguishes from siblings like 'get_dataset' by emphasizing the list and pagination.

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 use for browsing datasets via pagination, but does not explicitly state when to use this tool versus alternatives like 'get_dataset' or 'list_editions'. No when-not-to-use or alternative guidance is provided.

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. The description adds value by detailing the specific return fields (edition label, release date, state, latest version ID), which provides behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose, and no unnecessary words. Every sentence adds value: first states the action and scope, second describes return values and usage.

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

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

The tool is simple (1 parameter, list operation) and has an output schema. The description mentions all key return fields and provides downstream guidance, making it fully 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 dataset_id described as 'ONS dataset ID'. The description does not add further details about the parameter; it only mentions the dataset in the context of listing editions. Baseline 3 is appropriate as schema already covers it.

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

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

The description clearly states the tool lists all named editions of an ONS dataset, with specific examples ('time-series', 'annual'). It distinguishes from siblings by mentioning downstream tools like get_version and get_observations, providing context for its role.

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

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

The description explicitly says it returns data to use with get_version or get_observations, indicating when to use it. It does not provide explicit when-not guidance, but for a list tool with one parameter, the usage is clear from 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 read-only, idempotent, non-destructive. Description adds return fields and default behavior (active only). Does not mention pagination or limits, but adequate for simplicity.

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 plus a brief list of return fields. Every sentence is purposeful: purpose, usage, output. Front-loaded and concise.

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

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

For a simple listing tool with one optional parameter and no output schema, the description covers purpose, usage, return fields, and parameter behavior completely.

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. Description reinforces the default (active subscriptions) implied by the optional include_inactive flag, adding 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?

Description clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Implies alternatives (subscribe, unsubscribe).

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

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

The description states it 'Returns the full series JSON (description + observations)', adding value beyond annotations which already declare readOnlyHint, idempotentHint, and non-destructive 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?

Three sentences that efficiently convey purpose, distinction, return type, and naming context. No unnecessary words; well structured.

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

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

For a single-parameter tool with no output schema, the description adequately explains what the tool returns (full series JSON) and how to use it. The naming note avoids confusion with other implementations.

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

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

Schema coverage is 100%, so the schema already describes the uri parameter. The description provides an example and mentions it's a www.ons.gov.uk URI, but this largely duplicates the schema's description. Minimal added semantic value.

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

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

The description clearly states the verb 'Fetch', the resource 'a single UK ONS time series', and the method 'by its www.ons.gov.uk URI'. It also contrasts with 'filterable datasets', distinguishing it from sibling tools like get_dataset.

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 distinguishes this tool from 'filterable datasets above', providing clear context for when to use this API. While it does not list all alternatives, the mention of 'get_series is used by many other packs' helps differentiate it from similarly named tools.

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

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

Beyond annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and the claim_token return/read-back workflow ('Filing without an account returns a claim_token; pass it back later...'). These are non-obvious behavioral traits not captured by readOnlyHint/destructiveHint 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 front-loaded with the primary purpose and use cases. Every sentence carries guidance (scope boundaries, claim_token flow, rate limits, roadmap impact), yet a few clauses could be tightened without loss. It is structured well with clear thematic shifts.

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 nuanced scope (Pipeworx-only), input parameters (type, context, message, claim_token), and lack of output schema, the description fully explains the claim_token lifecycle and expected usage. It covers exclusions, data format, limits, and downstream effects, leaving no critical gaps for a feedback 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%, but the description adds workflow meaning: claim_token is clarified as 'Read the reply to a report you filed earlier' with the instruction to pass no other arguments, and message guidance specifies 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This adds real semantic value beyond the raw schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' and then enumerates concrete use cases (bug, feature/data_gap, praise). This specific verb+resource framing distinguishes it from sibling tools like ask_pipeworx or discover_tools.

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

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

It gives explicit when-to-use conditions ('Use when a tool returns wrong/stale data...'), explicit exclusions ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'), and a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists'). This is model 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: caching (5min-1h), data source (CF analytics-engine), and no PII.

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?

Description is well-structured, front-loaded with main action. Slightly verbose with numbered use cases but each sentence adds value; 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?

For a read-only trending tool with one optional param, description covers purpose, use cases, caching, and data source. Return is described (top tools, packs, volume). Could mention count limits, but not essential.

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 window parameter with enum. Description adds semantic context: shorter windows for hot trends, longer for steady-state demand, enhancing the schema 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?

Description clearly states verb 'returns' and specific resource: 'top tools, top packs, and total call volume'. It distinguishes from siblings like discover_tools by focusing on trending call volume.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment). Does not explicitly state when not to use, but 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?

The description adds substantial behavioral context beyond the annotations, which already declare readOnlyHint=true. It explains internal logic: monotonicity checks, partition sum verification, semantic anchor (Jaccard ≥ 0.30), partition filter (placeholder slugs), and fill check against CLOB depth. It warns when a signal should not be traded.

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, using labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence serves a purpose, and the main purpose is front-loaded. It could be slightly more concise, but it earns its length by providing necessary details.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers expected outputs (opportunities array with gap_pp, suggested_trade, reasoning) and special cases (fill check, placeholder filter). It also references a companion tool for custom sizing.

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%, providing a baseline of 3. The description adds value by explaining the distinction between event and topic modes, giving example inputs ('fed-decision-may-2026'), and specifying the behavior of each parameter. 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 clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three modes (no args, event, topic) and explicitly distinguishes from the sibling tool polymarket_fill_risk by directing users to it 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?

The description provides clear guidance on when to use each mode: recommended for specific markets (event) and cross-event scanning (topic). It also tells users not to trade if realizable_edge_pp ≤ 0 and to use polymarket_fill_risk for custom sizing. However, it does not explicitly differentiate from other sibling tools like polymarket_edges.

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 context beyond annotations, including caching behavior (cached 1h at KV level keyed on all knobs), the three response segments with detailed model logic (e.g., per-sport alpha in partition_overround), diagnostic output to explain empty segments, and tradeable-edge knobs. It does not contradict the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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 very long and includes detailed internal logic (e.g., per-sport α values, placeholder-slug filter details) that some agents might find excessive. While well-structured with sections, it could be more concise without losing essential 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 the tool's high complexity (9 parameters, 3 model families, caching, diagnostics) and the absence of an output schema, the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, _diagnostics) and how knobs affect output, meeting all needs for an agent to correctly select and 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 baseline is 3. The description adds meaningful context for several parameters, such as slippage_pp (recommended value, explanation of market conditions), min_partition_leg_kelly (explains why parent-level Kelly is 0 and when to use this knob), and categories like 'Tradeable-edge filters'. 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 clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on a specific data source and providing a consolidated 'what should I bet on today' view.

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 it is built for 'what should I bet on today' and that agents can discover opportunities without paging, but it does not explicitly contrast with alternatives like polymarket_arbitrage or polymarket_fill_risk, nor does it state 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?

Description adds rich behavioral details beyond annotations: response structure, computational methods (trend, decay), snapshot gaps, TTL limits, and the fact that decay uses daily closes, not intraday. 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?

Description is long but information-dense and front-loaded with core purpose. Could be slightly more concise but not wasteful.

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 fully explains response fields (tracked, expired, snapshot_dates) with subfields and meanings, plus tool limitations. Complete for a tool with 2 parameters.

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% with descriptions. Description adds context: default and max for days, examples for window families (24hr, 1wk, 1mo).

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 'Edge persistence and decay telemetry' and answers a specific question, distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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 when to use it (to differentiate old vs new wide edges) but does not explicitly mention when to avoid it or name 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?

Despite annotations already providing readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds significant behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warns about thin legs and forced directional risk. 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?

Well-structured with bold labels, parenthetical clarifications, and clear separation of modes. Dense with information, but could be slightly more concise. Still earns its length by being highly informative.

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, four parameters, no output schema), the description is remarkably complete. It covers return fields for both modes, explains the verdict system, thin legs, forced directional risk, and profit_usd. Agents have all necessary context to use it correctly.

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

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

Schema has 100% description coverage for all 4 parameters, but the description adds value by explaining parameter behavior in context (e.g., size_usd interpretation differs for single-market vs basket mode). Defaults and clamping are clarified.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinguishes between single-market and basket modes with specific verbs and resources. Differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk.

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 when to use: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. Explains why with concrete risks (theoretical overround not capturable, partial basket fills create unhedged positions).

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 is exceptionally transparent about behavior: both modes run the same matcher, unknown legs are never paired, compatibility codes appear even with matched pairs, null temporal_alignment means uncomputable rather than aligned, spreads are gross of Kalshi fees, and skipped counters are explained. This goes far beyond the readOnly/openWorld/idempotent annotations and adds real cautionary 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 long, but nearly every sentence contributes a necessary caveat, mode rule, or field meaning, and the core purpose is front-loaded in the first sentence. The density and repeated warnings make it slightly harder to scan than ideal, but it is not padded.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does so thoroughly: per-venue prices, top_spreads_pp, compatibility codes, per-leg flags, skipped results, temporal alignment semantics, fees exposure, and the rareness of real spreads. An agent has enough context to call the tool and interpret results safely.

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

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

The schema already provides 100% coverage for all three parameters, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how topic mode relates to the explicit override parameters, that both modes run identical matching, and how the two explicit parameters interact with the topic-mapped side.

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 cross-venue spreads between Kalshi and Polymarket for the same resolving question, which is specific and distinct from most siblings. It doesn't explicitly name or contrast sibling tools, and it uses a noun phrase rather than an imperative verb, so it stops just short of a 5.

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

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

The description gives strong context on when to use each mode: the 10 pre-mapped topic shortcuts for common macro events, and explicit ticker/slug pairs for custom pairings. It flags that pre-mapped topics often produce warnings rather than tradeable spreads, but it doesn't explicitly tell the agent when to prefer a sibling tool like polymarket_arbitrage or polymarket_edges.

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

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

Adds scoping information (by identifier) beyond the readOnlyHint and idempotentHint annotations. Does not contradict annotations. Lists both behaviors (retrieve vs list all keys).

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

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

Two sentences with no wasted words. Each sentence serves a purpose: first defines core functionality, second provides context and examples. Front-loaded with the 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 no output schema, the description adequately covers behavior and scoping. Could detail return format but is sufficient for a simple retrieval tool. Complements annotations well.

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

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

The description adds meaning beyond the input schema by explaining that omitting the key lists all keys. Schema coverage is 100%, but the description enriches with usage context and pairing with other tools.

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

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

The description clearly states the tool retrieves or lists memory values, using specific verbs 'retrieve' and 'list'. It distinguishes itself from siblings by explicitly naming '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 cases (e.g., user's ticker, address) and explains when to use ('without re-deriving'). Mentions pairing with remember/forget, but could be more explicit about when not to 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?

Discloses return fields (source, citation_uri, payload), mark_read behavior, and feed persistence. Annotations already indicate readOnly and idempotent, but description adds valuable behavioral context beyond those.

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?

Four sentences, each serving a purpose: main action, return details, filter/mark_read usage, and polling/alternative access. Front-loaded with key information, 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?

Covers all essential aspects for a read-only, polling-friendly tool: what it returns, how to filter, mark_read effect, and alternative access method. No output schema, but description compensates well.

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

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

Adds usage context for type, since, and mark_read parameters beyond the schema descriptions (e.g., examples, effect of mark_read). Schema coverage is 100%, so baseline is 3; extra context 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?

The description clearly states it pulls fired events from subscription feed, specifying the action and resource. However, it does not explicitly distinguish from sibling tools like recent_changes, which may cause ambiguity.

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

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

No guidance on when to use this tool vs alternatives. It mentions polling works fine and an alternative HTTP endpoint, but lacks explicit when-to-use or when-not-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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: fan-out to multiple data sources (SEC, GDELT/GNews, USPTO), fallback logic, soft-failure for USPTO, and return structure details. It does not contradict annotations. The only minor gap is lack of explicit mention of rate limits or error handling beyond the fallback, but overall well-covered.

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?

A single, well-structured paragraph that front-loads with practical query examples, then succinctly covers sources, parameter details, return format, and disambiguation. Every sentence serves a purpose; no redundancy.

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

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

Given the tool's complexity (multiple external APIs, fallback logic, diverse data sources) and the absence of an output schema, the description comprehensively covers inputs, behavior, and outputs. It specifies sources, fallback conditions, return structure, and use case comparisons, ensuring the agent can 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?

All three parameters are fully described in the schema (100% coverage). The description adds value by explaining that value can be ticker or CIK, providing examples and recommended default for since (30d/1m), and clarifying the role of each parameter in context. This enriches the schema information.

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 exact purpose: providing a change feed for a company over a time window via a single parallel call, with concrete examples like "What's new with X" and distinguishes from sibling tool entity_profile. It uses a specific verb-resource combination and clearly scopes the tool's function.

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 (recent changes) and when not to use (prefer entity_profile for static profile). Includes typical use cases and window recommendations, making it easy for an agent to decide between this and alternatives.

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

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

Annotations provide idempotentHint and readOnlyHint; description adds key behavioral details: scoped by identifier, persistence differences for authenticated vs anonymous users (24-hour retention), and data type (key-value, any text). 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?

Description is a single paragraph but front-loaded with purpose, followed by usage context and retention details. Every sentence adds value, though could be slightly more concise.

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

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

With no output schema, description covers persistence, scoping, and pairing. For a simple storage tool with two required params, it provides sufficient context for correct invocation.

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

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

Schema has 100% coverage with clear descriptions for key (examples) and value (any text). Description reinforces but does not add new semantic meaning beyond schema examples.

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

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

Description uses specific verb 'Save data' and resource 'key-value pair'. It explicitly distinguishes from sibling tools 'recall' and 'forget' by mentioning them as complementary actions.

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?

States when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall/forget, but does not explicitly state when not to use or provide 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 establish readOnly/openWorld/idempotent/non-destructive behavior, and the description adds substantial behavioral context beyond that: internal cascade across multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit unresolved reporting, ambiguity handling via figi_candidates, and the ISIN-to-LEI mapping behavior. No contradiction with annotations.

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

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

The description is long but dense and front-loaded with examples and the key 'Use FIRST' directive. Each subsection earns its place by clarifying supported types, edge cases, and behavior. It could be trimmed slightly, but the structure is logical and scannable.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so well: it names figi_candidates, unresolved, source labels, RxCUI/ingredient/brand, and enrichment degradation. Given the tool's complexity and breadth of entity types, the description is complete enough for an agent to select and invoke it correctly.

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

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

Although the schema covers 100% of parameters, the description adds significant semantics: examples of ticker/CIK/ISIN/name inputs, the distinction between brand and generic drug names, and the crucial guidance that bond lookups should receive the issuer name exactly as printed, not the full noun phrase. This materially improves correct invocation.

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

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

The description states a precise verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools like entity_profile by scoping itself to identifier lookup rather than broader profiling, and it enumerates specific supported types and example queries.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when identifiers may not resolve, when ambiguity is handled via figi_candidates, and how enrichment degrades gracefully. It does not explicitly name sibling tools as alternatives or state when not to use it, but the direction is clear and actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds that it probes entities with ai_visibility_check and provides a ranked list with score, confidence, and signal density. 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 plus an example, front-loaded with key action and purpose. Every sentence earns its place with 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?

Despite no output schema, description adequately explains return structure and key parameters. Additional detail on how models and context work would be nice but not essential.

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 value by explaining the first entity is the 'subject' and rest are competitors, and clarifies the models parameter behavior. 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 states it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison), making purpose unambiguous.

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

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

Explicitly mentions usage for competitive AI-marketing audits with an example. While it doesn't state when not to use or list alternatives, the context of comparing multiple entities is clear enough.

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?

Discloses critical behavioral traits beyond annotations: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully with sources_failed reporting. This adds context for timeout handling and robustness 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?

Single paragraph packs purpose, usage, limitations, and behavior with no wasted words. While structured for readability, a more scannable layout (e.g., bullet points) could improve efficiency. Still highly 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?

Given the tool's complexity and absence of output schema, the description fully covers return structure (summary block fields, per-advisory details, links, alternative versions), error handling, and version behavior. 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 already provides comprehensive descriptions for both parameters (package, version). The description adds minor clarification about scoped packages and confirms default version behavior. Baseline 3 is appropriate as schema coverage is 100%.

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

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

Clearly describes a composite check for evaluating npm packages, specifying the data sources (deps.dev, bundlephobia) and the categories (license, advisories, size, etc.). Distinguishes itself from single-source tools by highlighting the all-in-one nature.

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

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

Explicitly advises when to use ('is X safe / popular / small', 'what does adding lodash cost me') and states the ecosystem restriction (NPM only in v1), with a pointer to alternatives (PyPI, etc. via deps.dev). Provides clear adoption guidance.

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

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

Beyond annotations (readOnly, idempotent, nondestructive), the description discloses underlying model (BGE-base-en), chunking (500-char overlapping windows), similarity metric (cosine), max input (200K chars), truncation behavior (flagged), and output details (character offsets).

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

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

Single paragraph with front-loaded purpose and efficient, informative sentences. No redundant or vague language; 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?

Despite no output schema, the description clearly explains output (passages with offsets and scores), pairs with another tool, and covers all necessary aspects for an agent to correctly select and 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% with descriptions for each parameter. The description adds usage context for 'text' (already-pulled document) and 'query' (natural-language examples), and reiterates 'limit' constraints, providing value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies inputs (text + query) and outputs (top-N passages with offsets and scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. Pairs with ask_pipeworx_grounded for grounding, providing clear guidance on when to use this tool vs alternatives.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds value by disclosing mutation (creating subscription), returning subscription ID, authentication needs, and delivery constraints (e.g., 10/day sms cap, webhook signing). No contradictions with annotations.

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

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

The description is a single paragraph but is front-loaded with purpose and returns. It efficiently packs information without redundancy. Slightly lengthy due to examples, but each 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?

Given the tool's complexity (multiple types, nested params, optional delivery channels), the description covers all necessary aspects: preconditions, type-specific params, delivery options, post-conditions (returns subscription id). No output schema, but return value is mentioned. Complete for agent decision-making.

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

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

Schema coverage is 100% for 3 parameters, and the description adds extensive detail beyond the schema: explains each type with examples (e.g., sec_8k items), params structure, delivery options with constraints (phone verification, webhook HMAC). This fully compensates for the schema's brevity.

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. Returns the new subscription id.' This is a specific verb+resource, and it distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions.'

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

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

Provides explicit context: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It details types and delivery channels, but doesn't explicitly contrast with alternative tools like 'list_subscriptions' or 'recent_alerts.' Still, the context is clear enough for most use cases.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about returning example questions and tool shapes, enhancing transparency 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?

Description is informative and well-structured, with trigger phrases and return details front-loaded. Slightly long but 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?

With no output schema and only one optional parameter, the description fully explains the tool's purpose, usage, and return value. 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% and describes the 'topic' parameter. Description adds meaning by explaining that omitting topic gives a full spread, and lists example focus areas. Baseline 3, but adds extra context.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, serving as the onboarding entry point. It distinguishes itself from siblings by being the first tool to use when unsure.

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

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

Explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also instructs when to pass 'topic' and what values to 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 (readOnlyHint: false, destructiveHint: false, idempotentHint: true) already indicate the safety profile. The description adds valuable context: ownership enforcement, soft-deactivation (row deactivated not deleted), and data retention (historical events stay via recent_alerts). This 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?

The description is two sentences, front-loads the main action, and includes essential behavioral details without any unnecessary words.

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

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

For a single-parameter tool with good annotations, the description covers the core action, ownership, data lifecycle, and connection to sibling tool recent_alerts. It is complete enough for an agent to understand 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?

The input schema has 100% coverage (description for 'id' says 'Subscription id (uuid) returned by subscribe'). The description does not add any further semantics for the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It distinguishes this tool from sibling tools like subscribe and list_subscriptions by specifying the cancellation action and ownership enforcement.

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 context on when to use the tool (to cancel a subscription) and includes a constraint ('Ownership is enforced — you can only cancel your own subscriptions'). It also hints at the post-cancellation state (historical events via recent_alerts). However, it does not explicitly list alternatives or when not to use.

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

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

Beyond annotations (read-only, idempotent), the description explains critical behavioral nuances: the meaning of each verdict type, the non-evidentiary nature of could_not_verify, and the unsupported vs. could_not_verify distinction. This significantly reduces misinterpretation risk and goes well beyond the structured hints.

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

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

The description is moderately long but efficiently structured with trigger phrases up front, then a clear purpose statement, and a concise list of returns/verdicts. Every sentence adds value, including the practical warning about could_not_verify. Slight density prevents a perfect score.

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

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

Given the tool's complexity and the absence of an output schema, the description fully covers return values (verdicts, value, citation, reasoning) and explains error conditions. It also explains routing logic and caller obligations, making it self-contained for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with both 'claim' and 'tolerance_pct' thoroughly documented in the input schema. The description itself adds no technical parameter details beyond mentioning percent-delta math, so it does not need to compensate for schema gaps. Baseline 3 is appropriate.

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

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

The description clearly identifies claim verification as the tool's function, with specific verb ('verify') and resource (natural-language claim), plus trigger phrases. It distinguishes from sibling tools by outlining its dual-path routing for financial vs. non-financial claims, making the scope unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving direct usage context. It also clarifies that financial claims follow a structured path and everything else falls through to a grounded pipeline, though it doesn't name alternative sibling tools for other query types.

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