Met No

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, which the description does not contradict. However, the description adds no additional behavioral context, such as temporal resolution, units, or geographic limitations beyond the word 'Norway'.

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

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

The description is a single, front-loaded sentence that is free of extraneous text. It is concise, though perhaps overly terse given the missing parameter 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 simple input schema (3 params) and the presence of an output schema, the description provides only the core purpose without contextual details like expected usage patterns or coordinate interpretation. It is minimally adequate but not sufficient for an agent to fully understand the tool's capabilities.

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

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

With schema description coverage at only 33%, the description needed to explain the coordinate parameters and any constraints. It does not mention lat/lon or how areaclass relates to forecast granularity, failing to compensate for the sparse 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 identifies the tool as providing air-quality forecasts for Norway, which distinguishes it from sibling environmental forecast tools like oceanforecast and sunrise. However, it lacks an explicit verb (e.g., 'retrieve' or 'get'), making it a noun phrase rather than a full action statement.

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 is provided about when to choose this tool over alternatives. The description does not mention use cases, prerequisites, or distinguish from other forecast-related tools, leaving the agent to infer from the name.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavior: it discloses that 'BYO key' means the user pays Anthropic directly and that the key is passed through to api.anthropic.com. It also describes the return shape (per-model score, confidence, signals, raw_response), which is not in annotations.

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

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

The description is compact (three sentences) and front-loaded: the first sentence gives the core purpose, the second covers configuration, and the third summarizes output and use cases. Every sentence adds essential information with no filler.

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

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

Even though there is no output schema, the description explicitly lists the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). It also explains the model selection, API key requirement, and disambiguation context. This is sufficient for a agent to invoke the tool correctly.

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

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

The schema has 100% parameter coverage with descriptions. The description adds extra meaning: it states the default model (Workers AI Llama-3.3-70b) is free, clarifies the _apiKey is only needed when Anthropic is in models, and gives examples for the entity parameter. This goes beyond the schema's own 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 function: probing LLMs for knowledge about an entity and scoring visibility. It uses a specific verb ('Probe') and resource ('LLMs'), and the outcome (0-100 visibility score) is explicit. It also distinguishes itself from broader research tools by focusing on AI visibility scoring.

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 concrete use-case context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional Anthropic key. However, it does not explicitly mention when not to use it or contrast with sibling tools like scan_competitor_ai_presence, so it lacks explicit exclusion guidance.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive. The description adds valuable context: routes to many tools, fills arguments automatically, returns pipeworx:// citation URIs, works on every tier with one fast call. These details go beyond the annotation flags without contradicting them.

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

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

The description is long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH'). It includes domain lists, trigger phrases, examples, and alternative tools. Some redundancy exists (the domain list partly overlaps with examples), but each sentence contributes to the tool's role as a default router.

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 explains the return format (structured answer with citation URIs) and covers use cases, scope, alternatives, and operational guarantees. It fully equips an agent to decide when and how to invoke this tool and what to expect.

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

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

Schema coverage is 100% with aliases fully documented. The description includes example questions but no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema carries the parameter information and the description doesn't need to compensate.

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 routes factual questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It distinguishes itself from siblings by positioning ask_pipeworx as the default entry point and explicitly naming alternatives 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?

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', trigger phrases, example queries), when-not-to-use (step up to grounded or deep_research for specific needs), and direct alternatives. This is a model of usage instruction.

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 that this is an experimental edge with candidate routing improvements, that no candidate is active right now (with a specific date), and that results are compared against the stable router. It also clarifies it 'Falls back to nothing — this IS a full working router', providing crucial context about its operational status and experimental nature not captured in 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, well-structured paragraph that front-loads the beta relationship and provides precise details (5,529 tools, specific retire date, comparison process). Every sentence adds necessary context, though it is longer than strictly necessary. No verbosity or redundancy.

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

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

The description covers the tool's current status, relationship to stable ask_pipeworx, usage rationale, and experimental behavior. It mentions 'same response shape' but does not specify the shape in absolute terms; however, given the sibling context and lack of output schema, this is acceptable. The description is sufficiently complete for a complex router tool.

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

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

The input schema already describes the 'question' parameter and all aliases with 100% coverage. The description only says 'same arguments' without adding semantic detail beyond what the schema provides. Thus it does not meaningfully enhance parameter understanding, matching the baseline for full schema coverage.

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

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

The description clearly states it is the 'Beta version of ask_pipeworx' with the same tools, arguments, and response shape, while being an experimental 'universal router'. It distinguishes itself from the stable ask_pipeworx by emphasizing candidate routing improvements and being the 'experimental edge', making its purpose and relationship to siblings explicit.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies that currently no candidate is active, so it matches ask_pipeworx exactly. However, it does not explicitly state when NOT to use it (e.g., if you need stable behavior), leaving some room for interpretation.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the internal routing to 5,529 tools, the argument-filling and data-fetching process, and the strict extraction from tool results. It also details the return structure with refusal reasons and mentions the extra LLM call cost, providing rich behavioral context beyond the annotation 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 a dense but efficient paragraph; every sentence adds value—purpose, mechanism, return format, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the main purpose and remains succinct despite its detail.

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

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

For a tool with a single required parameter but complex behavior, the description covers the routing mechanism, extraction rule, exact return schema (including refusal cases), and usage context with examples (financial verdicts, legal claims, medical lookups). It also explains the cost trade-off, making it fully self-contained for invocation decisions.

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

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

The schema covers all six parameters (aliases for question) with 100% description coverage, so the baseline is 3. The description adds no additional parameter-specific semantics beyond referring to the natural-language question, which the schema already documents adequately.

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 'Hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from sibling ask_pipeworx ('Same routing as ask_pipeworx'), establishing a specific verb+resource with a clear differentiation. It further details that the tool extracts answers using only the tool result content, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and contrasts with the alternative: 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, giving clear trade-off information for choosing between this and the sibling tool.

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

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

The description discloses a wealth of behavior beyond the annotations (readOnlyHint, openWorldHint, idempotentHint): resolver contract with match confidence and alternatives, parent_event extractor, fallback/retry fields, safety short-circuits ('low_confidence_match' and 'market_closed_or_inactive'), wide-spread tradeability notes, and cancellation-rule parsing. It explicitly warns to inspect resolver outputs before trusting analysis. This is far beyond what annotations convey and no contradictions exist.

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

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

The description is long but well-structured with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It is front-loaded with the core purpose and use cases. Every section adds necessary operational detail for a complex fan-out tool; the length is justified, though it could arguably be trimmed without losing 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, the description carries the burden of explaining return values and edge cases. It does this extensively: result.market fields, result.analysis fields, result.evidence keying, resolver contract, parent_event extractor, news fallback fields, safety statuses, and cancellation-rule risk. Concrete fan-out examples (BTC, Fed, Hormuz, Yankees) and explicit warnings (e.g., 'ALWAYS inspect these before trusting the analysis block') make it highly complete for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema for parameters; it reinforces that 'market' accepts slug/URL/question text and mentions depth behavior, but these are already in the schema. The parameter examples (like 'will-bitcoin-reach-100k-in-july-2026') appear in the schema's examples array. Thus the description provides little extra parameter value.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from specialized siblings like polymarket_arbitrage or polymarket_edges by covering broad research and fan-out. The stated use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further cement its purpose.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke the tool. It does not explicitly name alternatives or exclusions (e.g., 'for arbitrage use polymarket_arbitrage'), but the use-case phrasing is sufficient for an agent to distinguish from sibling 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 the readOnly/openWorld/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS/FDA), correct handling of off-calendar fiscal years, sorting behavior, and citation URIs in the response. These behavioral details add significant value without contradicting any annotation.

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

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

The description is dense but every sentence serves a purpose: trigger examples, precedence instruction, per-type data explanations, sorting, and output format. It is front-loaded with the most critical information and avoids filler, making it appropriately sized for the tool's complexity.

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

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

Given the lack of an output schema, the description adequately explains the return contents (paired data + citation URIs) and sorting behavior. It could be more explicit about the exact response structure, but for a tool with two entity types, it provides sufficient context for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantics of type values ('company' pulls 10-K fundamentals, 'drug' pulls adverse-event/trial counts) and the expected format of values (tickers/CIKs vs drug names, 2–5 items). This goes beyond the bare schema but does not fully describe all edge-case formatting.

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 a side-by-side comparison tool for 2–5 companies or drugs, with explicit trigger phrases like 'X vs Y' and 'rank these companies'. It distinguishes itself from sequential lookups by emphasizing a single parallel call, making its purpose unambiguous and distinct from sibling tools.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear precedence guidance. It also details when to use type='company' versus type='drug' by listing the specific data points each pulls, which helps the agent decide between alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent safe behavior. The description goes far beyond by disclosing account requirements, parallel execution, gaps[] for unanswered facets, contradictions[], hop field, citation_uri fetchability only when source emits it, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is dense and every sentence adds substantive information, but is quite long for a tool description. It is well-structured and front-loaded with the critical account requirement, yet could risk overwhelming the agent with environmental specifics (e.g., exact signup URL, tool counts). Still, no wasted sentences.

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

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

Given the tool's complexity and no output schema, the description covers the return packet structure, evidence format, gaps, contradictions, citations, excerpting, and latency. It also names sibling tools for comparison, making this highly complete for an agent to select and anticipate outcomes.

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 its depth enum description is already detailed. The description adds value by clarifying question granularity ('broad/multi-part is fine') and connecting depth values to gap recovery and contradiction scans, enriching practical semantics beyond schema.

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

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

The description clearly states the tool performs multi-source grounded research across structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes from open-web search and sibling ask_pipeworx, making its unique role unambiguous.

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

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

Explicit guidance is provided: use for broad/multi-part structured questions, prefer ask_pipeworx for single lookups or breaking news, and requires sign-in with paid tier for thorough depth. Also explains when deep_research will return mostly empty gaps, giving clear when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context beyond that by stating the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is valuable behavioral disclosure about output and efficiency, and there is 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 three sentences, front-loaded with the primary purpose. The long list of domains is somewhat verbose but serves to clarify the tool's coverage. Every sentence contributes meaning, and there is no wasted verbiage, but the domain list could be trimmed without losing core value.

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

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

For a discovery tool with no output schema, the description covers the what, when, and return format thoroughly. It explains that results include full schemas and curated examples, making them directly callable, and it clarifies when to invoke it first. Annotations cover safety, and the schema covers parameters, so no critical aspect 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%, with detailed descriptions for all six parameters (including aliases for query and a description for limit). The description itself does not add parameter-level semantics beyond what the schema already provides, but per the rubric, high schema coverage makes a baseline of 3 appropriate.

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

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

The description opens with 'Find tools by describing the data or task', a specific verb+resource statement. It clearly distinguishes this from sibling tools by positioning it as a meta-tool that returns tool names, descriptions, and schemas, while listing supported domains. This is not a tautology and fully differentiates from siblings.

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

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

The description provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' This tells the agent when to use it, and 'Call this FIRST' implies when not to use it (after the option set is known), but it does not name specific alternative tools or state explicit when-not conditions. Thus 4.

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 the parallel fan-out across EDGAR, XBRL, USPTO, news, and GLEIF, the exact return fields (cik, recent_filings, fundamentals, patents, news, LEI), the 'up to 5' filing limit, the sort order for fundamentals, and even the USPTO API sunset/soft-fail behavior. This is rich, honest behavioral context.

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

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

The description is longer than ideal but every sentence carries substantive information: example queries, scope, return summary, and key caveats. It is front-loaded with the most important usage cues and then flows into return details. It could be tightened into bullets, but it is not bloated.

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 must explain what the tool returns, and it does so thoroughly: cik/company_name, recent_filings with URIs, 10-K fundamentals, patents with a sunset caveat, news fallback chain, and LEI. Combined with the parameter constraints and alternative guidance, this gives an agent everything needed to invoke the tool and interpret the result.

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

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

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds value by giving concrete examples ('AAPL', '0000320193'), emphasizing the zero-padded CIK format, and reiterating that names are not supported. This goes slightly beyond the schema but does not add deep new semantic detail for every parameter.

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

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

The description opens with concrete user phrasing ('Tell me about X', 'research Acme') and states a specific action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from sibling tools by naming 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by pointing to resolve_entity for name-only inputs.

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

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

It explicitly tells when to use the tool ('when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first'). It also frames this as the preferred alternative to chaining multiple single-purpose lookups, giving practical decision 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 disclose read-only, idempotent, and non-destructive behavior, so the description does not need to repeat that. However, it adds no new behavioral context (e.g., response size limits, pagination, or data freshness), providing only the output scope.

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, tightly worded sentence that front-loads the key info (10-day forecast) and enumerates output variables. 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?

This is a simple tool with a complete input schema and an output schema available. The description covers the essential output aspects (time horizon and weather elements), leaving no critical gaps.

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

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

The schema fully describes all three parameters (lat, lon, altitude) with 100% coverage. The description adds no extra meaning about the parameters themselves, so it meets the baseline for high schema coverage.

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

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

The description clearly states what the tool does: it provides a 'Compact 10-day forecast' and names the specific weather elements (temperature, precip, wind, cloud, humidity). This distinguishes it from sibling tools like nowcast or oceanforecast.

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?

There is no explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions or prerequisites. The '10-day' timeframe implies medium-range but does not say 'use nowcast for short-term' or otherwise contrast with siblings.

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

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

The description adds context about clearing sensitive data and the fact that the memory was saved earlier, complementing the destructiveHint and idempotentHint annotations. It does not contradict the annotations, and 'Delete' aligns with the destructive flag.

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

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

Two sentences, front-loaded with the core action, followed by use cases and related tools. No fluff or redundancy.

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

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

For a single-parameter destructive action, the description covers what, when, and how, and references related tools. The annotations supply the safety profile, so 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 schema already covers the single parameter with a description ('Memory key to delete'), and the tool description repeats 'by key' without adding new meaning. With 100% schema coverage, the baseline of 3 applies.

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

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

The description uses the specific verb 'Delete' with the resource 'a previously stored memory' and specifies 'by key', clearly distinguishing it from sibling tools like remember and recall. It conveys the exact operation and scope.

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

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

It explicitly states when to use ('when context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall, giving clear context for when to choose this tool over related ones.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' disclosing network activity and output type. 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 concise and front-loaded with the main function, followed by behavioral details and use cases. Every sentence adds value, with no fluff or repetition. The structure is well-organized and easy to scan.

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 two-parameter tool with rich annotations and full schema coverage, the description is complete. It explains the output format ('single text blob'), the fetching behavior, and the use cases. No output schema exists, so the description adequately covers what the agent needs to know 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 coverage is 100% with both url and max_links having clear descriptions. The description does not add parameter-specific detail beyond the schema, but it does mention 'key links' which aligns with max_links. Baseline of 3 applies since the schema fully handles parameter documentation.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL.' It specifies the exact output (standard llms.txt markdown) and distinguishes itself from sibling tools by focusing on file generation rather than analysis or checking. The mention of AI crawlers (ChatGPT, Claude, Perplexity) adds context for its intended use.

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.' This gives strong contextual guidance on when to use the tool, though it does not name alternatives or exclusion criteria. The contrast with siblings like ai_visibility_check is implicit but not directly addressed.

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, and destructiveHint=false, covering safety. The description adds context by specifying the return fields (id, type, params, etc.) and the caller-scoped nature of the listing, which annotations do not convey.

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

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

Two sentences: the first states purpose and return fields, the second gives usage context. No wasted words, front-loaded with the most important information.

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

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

For a simple list tool with full schema coverage and strong annotations, the description adequately explains what it returns, when to use it, and how it fits with subscribe/unsubscribe. No critical missing information.

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 the single parameter include_inactive clearly documented. The description does not need to add parameter-level detail; the schema carries the burden.

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

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

The description clearly states the tool lists the caller's active subscriptions, names the exact fields returned, and differentiates itself from sibling tools like subscribe and unsubscribe. The verb 'list' plus the resource 'subscriptions' is specific and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'before adding more' subscriptions and 'to find an id to cancel'. It does not name alternatives or exclusions explicitly, but the context is clear enough for an agent to select this tool over 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?

Annotations already declare read-only, idempotent behavior. The description adds context beyond annotations by specifying the 90-minute temporal scope and the behavioral consequence of sparse data outside the Nordics. This is valuable disclosure that helps the agent set expectations, though it does not detail the exact return format.

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, tightly written sentence that conveys purpose, time horizon, and geographic limitation without any filler. It is concise, front-loaded, and easy to parse.

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

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

The description, combined with rich annotations and an output schema, gives a reasonably complete picture for a simple tool. It covers the core function and the key limitation, and the schema example clarifies input usage. A slightly more explicit mention of parameter roles would elevate it further, but the current state is sufficient.

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 provides only bare parameter names (lat, lon) with no descriptions, and the description does not explain their meaning or usage. The geographic hint ('Nordics only') indirectly implies that lat/lon are coordinates, but this does not compensate for the lack of explicit parameter semantics, especially given 0% schema description coverage.

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

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

The description clearly states the tool provides a 90-minute precipitation nowcast, specifies the geographic scope (Nordics), and notes the sparse-data consequence outside that region. This distinguishes it from sibling weather tools like forecast or oceanforecast, making the purpose unmistakable.

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

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

The description explicitly states the regional limitation ('Nordics only') and warns about sparse data outside the region, effectively providing a when-to-use/when-not-to-use guide. However, it does not name alternative tools for other regions or longer timeframes, so it stops short of full guidance with alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds the specific output variables (current, wave height, sea temperature) but no further behavioral context such as rate limits, authentication, or data source reliability. No contradiction exists.

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

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

The description is a single, front-loaded sentence with no filler words. It is appropriately sized for a simple tool, but the brevity contributes to under-specification of parameters and usage context.

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

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

Given the tool's simplicity and the presence of an output schema, the description is minimally viable. However, it lacks usage guidelines and parameter semantics, and leaves ambiguous terms like 'current' unexplained. It does not fully cover the context an agent would need 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?

The input schema lists only lat and lon with no descriptions (0% schema coverage). The description does not mention or explain these parameters, missing the opportunity to clarify units, ranges, or required format. While lat/lon are inherently understandable, the description adds no 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 it provides an ocean forecast with specific variables (current, wave height, sea temperature). It distinguishes from general forecast tools by focusing on ocean conditions, but the term 'current' is ambiguous and there is no explicit differentiation from sibling tools like 'forecast' or 'nowcast'.

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 is provided on when to use this tool versus alternatives such as 'forecast' or 'nowcast'. The description implies use for marine conditions but does not state prerequisites, exclusions, or comparison to related 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?

The description discloses the claim_token flow (filing without an account returns a token for later status checks), rate limits (5 per identifier per day), and that it is free and doesn't count against quota. It also notes the team reads digests daily and signal affects roadmap. This adds rich context beyond the minimal annotations.

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

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

The description is a single dense paragraph but every sentence earns its place—it covers use cases, exclusions, token flow, rate limits, and quota impact. Slightly long but not bloated; it's front-loaded with the core purpose.

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 feedback tool with no output schema, it explains the claim_token response and how to retrieve status later. It also covers rate limiting, scope (only Pipeworx tools), and content guidelines. The main gap is not describing the exact response object beyond claim_token, but the tool's complexity is modest.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by advising what to put in the message ('don't paste the end-user's prompt', 'describe in terms of Pipeworx tools/packs') and explaining how to use claim_token for later replies. 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 the tool lets the user tell the Pipeworx team something is broken, missing, or needs to exist—a specific verb and resource. It distinguishes itself from siblings by focusing exclusively on feedback about Pipeworx tools, not data queries or other operations.

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 names use cases (bug, feature/data_gap, praise) and when NOT to use it (if the tool came from a different MCP server, file with that server instead). Even provides a diagnostic: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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 and idempotent annotations, the description adds important behavioral context: it is a 'self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'cached 5min-1h depending on window'. This discloses data provenance, privacy, and caching behavior.

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

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

The description is well-structured: a hook sentence, a returns statement, a 'Useful for' list, and a technical note. It is slightly longer than necessary but each sentence contributes distinct value and the formatting aids readability.

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

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

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description covers the essential aspects: what is returned (top tools, top packs, total call volume), data provenance, privacy (no PII), and caching. It gives enough to understand the tool's behavior.

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

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

The only parameter 'window' has 100% schema coverage with a clear enum description ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description does not add any additional semantics beyond what the schema already provides, so the baseline score of 3 applies.

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 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)', providing a specific verb and resource. The opening line 'What other AI agents are calling on Pipeworx right now' gives it a unique identity among sibling tools, distinguishing it from discover_tools and other query tools.

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

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

The description explicitly lists three use cases: discovering hot data sources for current events, confirming a canonical tool, and checking alignment with agent usage. This is clear contextual guidance, though it does not name alternative tools or specify when not to use this tool.

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

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

Beyond readOnlyHint/idempotentHint annotations, the description discloses the >3pp deviation threshold for signal emission, the >20% placeholder fraction that returns null, and the fill-check behavior that realizable_edge_pp ≤ 0 means 'do not trade it.' These are critical behavioral nuances not in any structured field.

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

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

The description is longer than average but efficiently organized with bolded mode headers such as SEMANTIC ANCHOR, PARTITION FILTER, and FILL CHECK. It front-loads the purpose and usage before diving into details, and every sentence adds unique information, though the density of technical callouts makes it less concise than a two-sentence tool.

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

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

In the absence of an output schema, the description specifies the response shape: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context, plus partition_check fields in event mode. It covers all three invocation modes, edge cases like thin legs, and delegation to polymarket_fill_risk, making it fully self-contained.

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

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

Both schema descriptions are dense, but the description adds concrete slug examples ('fed-decision-may-2026') and explains internal logic for each parameter: event walks child markets and checks ordering, topic flattens a union and applies Jaccard similarity. This transforms the parameters from simple strings into behaviorally rich inputs.

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 opening sentence 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' clearly specifies the verb, resource, and method. It further differentiates three call modes (trending_scan, event, topic) that map to distinct use cases, distinguishing it from siblings like polymarket_edges and polymarket_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?

It directly instructs: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It notes cross-event catches patterns single-event misses, and for custom sizing 'use polymarket_fill_risk', explicitly naming the alternative 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?

The description discloses extensive behavioral context beyond annotations: cached for 1 hour, response structure, why segments may be empty via _diagnostics, the 24h-move warning, per-leg Kelly behavior, and even admits limitations like the unreliable Fed signal and 'rare-by-design' concentrated longshots. This is exemplary transparency for a complex tool.

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

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

The description is dense and long, but every sentence carries important information about segments, response fields, knobs, and diagnostics. It lacks structured formatting (e.g., bullets), making it harder to parse, but the content justifies its length. It is appropriately sized for a tool of this 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 complexity, no output schema, and 9 parameters, the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), what each opportunity includes, how knobs filter, caching behavior, and why certain segments may be empty. This covers all essential invocation and interpretation needs.

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

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

Schema covers all 9 parameters with 100% description coverage, so baseline is 3. The description adds non-obvious semantics beyond the schema, such as how min_partition_leg_kelly applies to per-leg Kelly inside top_legs rather than the parent level, and how slippage_pp relates to net edge. This adds concrete 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's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb ('scan') and resource ('Polymarket markets'), and further clarifies the intended use case ('what should I bet on today'). It distinguishes itself from siblings by describing its unique three-segment response structure and model families.

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

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

It explicitly frames when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also gives guidance on filtering with knobs like min_liquidity and max_spread_pp. However, it doesn't explicitly mention when to prefer sibling tools like polymarket_arbitrage or edge_tracker, so it lacks explicit exclusions.

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

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

Annotations already declare read-only/idempotent, and the description adds substantial behavioral context: snapshots are written on cache-miss, gaps mean no scan, 60-day TTL limits history depth, and decay uses daily closes not intraday. This provides valuable insight beyond structured fields.

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 information, structured with 'Args:', 'RESPONSE:', and 'LIMITS:' sections. It is front-loaded with the core purpose and then details, making it efficient for an agent to parse.

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

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

With no output schema, the description fully documents the response structure including tracked[], expired[], and snapshot_dates[] with field semantics. It also covers limitations, making it complete for an agent to understand the tool's behavior without additional documentation.

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

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

Schema covers both parameters with descriptions, but the description adds meaning by explaining days has a default and max, and window defines the snapshot family. It clarifies each parameter's role in the telemetry context, going 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 explicitly states its function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a precise question ('how long has this edge existed and is it shrinking?'). It clearly distinguishes itself from sibling polymarket_edges by focusing on historical persistence rather than current edge values.

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?

Clearly conveys when to use by explaining that it provides edge history and decay analysis, while implying current edges are elsewhere. However, it does not explicitly name an alternative tool or state when not to use, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds significant behavioral detail: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict), explains the basket-mode interpretation of size_usd, and warns about forced_directional_risk. It does not describe rate limits or auth, but given the annotations, the extra detail justifies a 4 rather than a 3.

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

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

The description is dense and information-packed, but it is structured with clear sections (SINGLE-MARKET vs BASKET) and uses abbreviations and lists to compress a lot of detail. It is longer than ideal but every sentence adds value, covering modes, parameters, return fields, and usage guidance. The front-loading of the core purpose and the warning at the end make it effective despite length.

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

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

The tool has 4 parameters, no required params, 100% schema coverage, no output schema, and no nested objects. Given no output schema, the description compensates by enumerating key return fields for both modes (top_of_book, vwap_fill_price, etc.). It also covers the two main modes, defaults, and risk warnings. It lacks some details like pagination or error cases, but for a read-only analysis tool with rich annotations, it is largely complete.

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

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

Schema description coverage is 100%, so the schema already defines each parameter. The description goes beyond by explaining the distinction between single-market and basket modes for each parameter, clarifying the default behaviors (e.g., side default 'buy_yes' for single-market, 'auto' for basket), and interpreting size_usd differently per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional S'). This adds meaning beyond the schema's basic type/description, meriting a 4.

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

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

The description has a specific verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and it clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and market depth. It also specifies two distinct modes (single-market and basket) with concrete actions and outputs.

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

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

The description explicitly states when to use this tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains why (theoretical overround is not capturable on thin books; partial fills convert arbs into unhedged directional positions). It also names sibling tools and specifies the context, making the usage guidance highly 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 (readOnly, non-destructive), the description discloses rich behavioral traits: it explains the response structure (leg-by-leg prices, top_spreads_pp), the meaning of compatibility_warning in two distinct cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. It even warns that most pre-mapped topics return warnings, setting correct expectations. This far exceeds the minimal bar.

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 tightly packed with essential information. It uses clear section markers (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence covers a distinct aspect—why the spread exists, how to invoke, what the response contains, how to interpret warnings, and a caveat about tradeability. No filler or redundancy.

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

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

For a complex tool with no output schema, the description fully explains return formats, safety flags, and edge cases (temporal misalignment, non-equivalent bet shapes, unmatched leg pairs). It even interprets the meaning of skipped_cross_type/subtype counters. Given the absence of an output schema, this description carries the entire burden of explaining results and does so comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the concept of two modes and how topic vs explicit parameters interact, plus explains the override behavior that is also in the schema but frames it as a pairing strategy. It also gives the full list of topic shortcuts (already in schema) and example usage. This adds some value beyond the schema, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools (e.g., polymarket_arbitrage) by its cross-venue focus and explicitly states the tool compares bet shapes for equivalence, making the purpose unmistakable.

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

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

The description provides explicit usage modes: topic shortcuts vs explicit ticker/slug, and gives when-not guidance: 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so' and 'pre-mapped ≠ tradeable.' It also explains compatibility_warning conditions, telling users when the result is not an actionable arb. This is strong contextual guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by explaining the scoping to the agent identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all saved keys. This goes 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 three sentences, front-loaded with the core action, and every sentence contributes meaning. There is no redundant or filler content.

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

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

For a simple tool with one optional parameter and strong annotations, the description fully covers usage, scoping, and relationships to sibling tools. Return behavior (value or list of keys) is clearly implied by the description.

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

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

Schema coverage is 100% and the property description already states 'omit to list all keys.' The tool description repeats this behavior but adds no new parameter-level detail beyond what the schema provides.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys, using a specific verb ('Retrieve') and resource ('value saved via remember'). It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

The description gives explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives ('pair with remember to save, forget to delete'), providing clear when-to-use and sibling differentiation.

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

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

Beyond the readOnlyHint annotation, the description discloses that returned events include source, citation_uri, and raw payload, and that mark_read:true mutates read state to affect subsequent calls. It also confirms polling suitability, which is not evident from annotations alone.

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?

Five short sentences, all information-dense: purpose, return format, filtering, mark_read behavior, and an alternative endpoint. No redundant language.

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

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

The description covers the tool's return payload, key parameters, side effects, polling use case, and an alternative access method. Although it doesn't detail limit/unread_only behavior, those are covered in the schema and the tool is relatively simple.

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?

Since schema descriptions cover all 5 parameters at 100%, the description's added value comes from the concrete type example ('sec_8k') and explaining the side effect of mark_read on future calls. It does not elaborate on limit or unread_only, but the schema already does.

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

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

The description opens with the specific action 'Pull fired events from your subscription feed,' naming both the resource and the operation. It further distinguishes itself from siblings like list_subscriptions by focusing on alert events rather than subscription management.

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 a clear use case for polling and mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools. It also provides guidance on filtering by type and since, which helps the agent choose appropriate parameters.

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 multiple behavioral details beyond annotations: it fans out to SEC EDGAR, GDELT/GNews with fallback logic, USPTO with soft-fail due to PatentsView sunset, and returns changes[] grouped by source with total count and citation URIs. This is rich contextual information not inferable from annotations alone.

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 densely informative, with opening query examples that aid intent matching. It is front-loaded with the core purpose, and each subsequent sentence adds meaningful detail. The abundance of examples is slightly redundant but still earns its place for matching user phrasing.

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

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

Despite having no output schema, the description explains the return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs), the data sources, fallback behavior, and date format. For a 3-required-parameter tool with these annotations, this is comprehensive.

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

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

Schema description coverage is 100%, and the description largely mirrors the schema's parameter explanations (ISO/relative formats for since, ticker/CIK for value, company-only for type). It adds limited new param semantics beyond what the schema already provides.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with a specific verb ('change feed') and resource ('company'). It also distinguishes itself from entity_profile, which is the static profile alternative.

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 directs users to entity_profile when a static profile is needed, and provides typical usage guidance ('Use "30d" or "1m" for typical monitoring'). It also frames the tool for natural-language queries like 'What's new with X'.

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 idempotent and non-destructive behavior. The description adds valuable context: key-value storage scoped by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. This goes beyond annotations but stops short of explaining overwrite semantics.

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

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

Three sentences, front-loaded with primary purpose, then use case, then technical details. No filler, every sentence contributes essential information. Structure is logical and 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?

For a simple two-parameter memory tool with annotations and no output schema, the description covers the purpose, usage, persistence behavior, and relationships with recall/forget. It is complete and leaves no critical gaps.

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

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

The schema already documents both parameters with examples and descriptions (100% coverage). The description adds semantic meaning by explaining the key-value concept and the scoping by identifier, enriching the understanding of how the parameters are used together.

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 'Save' and the resource 'data the agent will need to reuse later', with concrete examples like 'resolved ticker' and 'user preference'. It also distinguishes this from sibling tools by pairing with 'recall' and 'forget', making the purpose unambiguous.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides examples. It also names the companions 'recall' and 'forget' as alternatives, giving clear direction on when to use this tool versus related 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?

The description adds substantial behavioral context beyond the annotations: it discloses that the tool cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, labels identifiers with sources, and explicitly reports unresolved identifiers. These details are not implied by readOnlyHint or idempotentHint and significantly aid the agent in predicting the tool's output and failure modes.

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

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

The description is long but densely packed; it front-loads with example queries to convey purpose, then details the supported types. Every sentence contributes information about usage, behavior, or supported inputs. It could be slightly more concise by trimming some parenthetical details, but the structure is logical and no sentence is wasted.

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

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

Given the tool has no output schema and only two simple parameters, the description provides a thorough explanation of return values, including conditional enrichments (LEI/FIGI), unresolved field handling, and graceful degradation. It also clarifies the types of entities supported and input formats, making the tool's behavior fully understandable without additional documentation.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description goes further by explaining the meaning of each type (company vs drug) and the expected input formats with examples (ticker, CIK, name; brand or generic). It also describes the return semantics for each parameter, which adds value beyond the schema's terse field descriptions.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers, with specific verbs like 'resolve' and a clear resource (identifiers). It distinguishes itself by listing supported types (company, drug) and mentioning the identifiers returned (CIK, ticker, LEI, FIGI, RxCUI), making it distinct from sibling tools like entity_profile or compare_entities.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly states when to use the tool, and the mention that it replaces 2-3 manual lookups gives context on its role as a preliminary step. However, it does not explicitly name alternative tools or say when not to use it, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a specific structure (score, confidence, signal density), giving behavioral insight beyond annotations without contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, and includes a practical example in a natural way. Every sentence earns its place with no redundant or vague filler.

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

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

With no output schema, the description fully specifies the return format (ranked list with score, confidence, signal density) and key input semantics (entities 2-8, first is subject). Combined with strong annotations for safety and read-only behavior, the tool is completely described 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 all four parameters are already documented. The description adds meaningful semantics by explaining that the first entity is treated as the 'subject' and the rest are competitors, and clarifies the context parameter is shared across probes, going 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 compares AI visibility across multiple entities side-by-side, mentioning the underlying ai_visibility_check probe and ranking by score. This distinguishes it from sibling tools like ai_visibility_check (single probe) and compare_entities, making its purpose unambiguous.

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

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

The description provides clear context for when to use this tool: for competitive AI-marketing audits, with a concrete example. It does not explicitly name alternatives or exclusions, but the context and reference to ai_visibility_check imply the appropriate scenario versus single-entity checks.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses critical behavioral traits: partial failure handling ('sources_failed will list it if it times out'), latency caveats ('first measurement can take 5-30s'), and the exact structure of the returned summary block. This goes well beyond the annotation baseline and fully informs the agent.

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

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

The description is dense but every sentence earns its place: purpose, usage, return details, ecosystem scope, and failure behavior. It is somewhat long but appropriately so for a composite tool; could be slightly more streamlined but remains well-structured and front-loaded.

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

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

Given no output schema, the description thoroughly explains return values (summary fields, per-advisory detail, links, alternative versions). It also covers failure modes, performance expectations, and ecosystem limitations, making it fully complete for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only minor semantic nuance (e.g., 'NPM ecosystem only' clarifies the package parameter) but mostly the schema already carries the meaning. No significant enrichment beyond the structured fields.

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 begins with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly states the tool's function and distinguishes it from siblings by naming the fan-out sources (deps.dev and bundlephobia) and the NPM ecosystem focus.

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

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

Explicit guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also names an alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), making when-to-use vs alternatives crystal clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive hints. The description adds rich behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap, truncation with flagging, and return fields (offsets, similarity scores). This substantially exceeds the annotation baseline and provides valuable operational transparency.

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

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

The description is three sentences, front-loaded with the core purpose, then elaborated with usage context, pairing guidance, and technical parameters. Every sentence contributes distinct information and there is no fluff or repetition of schema field names.

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

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

Despite lacking an output schema, the description states what is returned (top-N passages with character offsets and similarity scores). It also covers input limits, truncation, and a pairing workflow. Combined with strong annotations and schema, this description fully equips an agent to invoke the tool correctly.

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

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

Schema descriptions cover all parameters, so baseline is 3. The description adds useful context beyond the schema: it clarifies that 'text' should be already-fetched content, explains the truncation/flagging behavior for long inputs, and provides a concrete example query for 'query'. These additions enhance understanding without redundancy, warranting a 4 rather than a 3.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' and distinguishes it from siblings by emphasizing it operates on already-retrieved text rather than external sources. It specifies concrete use cases (SEC 10-K body, article) and output (top-N passages with offsets and scores), making its purpose unmistakable.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded, advising to 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use guidance and names an alternative tool, exceeding basic usage expectations.

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 the annotations, including authentication requirements, SMS rate limits (10/day), phone verification, webhook auto-disable after 10 failures, and the fact that the feed is always on. It also discloses the return of a subscription id and the one-time webhook secret, which aligns with the openWorldHint annotation without contradicting any 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 dense but logically organized: core action, return value, prerequisites, supported types, and delivery channels are presented in sequence. Every sentence adds necessary information without fluff, though length is considerable.

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 adequately covers return values (subscription id) and provides sufficient guidance for setup, including auth, channel options, verification, and rate limits. It addresses the complexity of three parameters and nested delivery objects comprehensively.

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

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

The description enriches the parameter understanding with concrete examples for each subscription type (e.g., items:['5.02'] = officer change for sec_8k, topic:'fed' for polymarket_edge) and detailed delivery channel requirements such as phone verification and rate limits. The input schema already provides 100% coverage, so this added guidance raises the score to 5.

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

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

The description uses a specific verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), clearly distinguishing this from sibling tools like list_subscriptions or unsubscribe. It also enumerates supported subscription types, making the purpose unmistakable.

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

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

The description establishes clear context for use: it requires a Pipeworx OAuth account, and explains that anonymous/BYO users cannot persist subscriptions. It also directs users to the persistent feed via recent_alerts or a public URL, implying the tool is for creating subscriptions while consuming events happens elsewhere. However, it does not explicitly name alternatives for viewing or canceling subscriptions.

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

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

Annotations already cover readonly, open-world, idempotency, and non-destructiveness. The description adds context about the output structure (category-bucketed examples, exact tool + argument shape) and the effect of the topic parameter. It doesn't contradict annotations and provides useful non-obvious details about the returned data.

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 long sentence but well-structured with dashes and examples. It front-loads the key phrases and packs useful details without repetition. While it could be split into shorter sentences, every clause contributes meaning, keeping it reasonably concise given the tool's coverage.

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

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

Despite lacking an output schema, the description thoroughly covers the return type (category-bucketed example questions, exact tool + argument shape), the data source (live catalog of thousands of tools), and invocation modes (no args vs topic). It also ties into meta-tool discovery, making it fully self-contained for a new user.

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's topic description is simple and covered 100%, so baseline is 3. The description adds value by listing concrete topic examples ('finance', 'pharma', 'betting') and explaining that omitting the parameter yields a cross-category spread, giving practical guidance not in the schema.

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

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

The description clearly states the tool's purpose: the onboarding entry point for Pipeworx, returning category-bucketed example questions with exact tool-argument shapes. It uses specific verbs ('returns', 'focus') and draws on a live catalog, and it distinguishes itself from siblings by explicitly marking its first-use role and by mentioning meta-tools (ask_pipeworx, entity_profile, compare_entities).

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

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

The description provides explicit when-to-use 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.' It also explains usage modes (no arguments for full spread, pass topic to focus). It does not explicitly discuss when-not-to-use or name comparing alternatives, but the guidance 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the domain of data (sunrise/sunset/moon events) and the date scoping, which is useful context but not deeply behavioral. 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, front-loaded sentence that efficiently conveys the tool's essence without wasted words. It is concise and to the point.

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 output schema exists and annotations cover safety, the description is mostly adequate. The main gap is the lack of explanation for lat/lon, which are the required parameters. Overall, it is complete enough for a simple tool but leaves one significant ambiguity.

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 exactly 50%; lat and lon lack descriptions. The description only mentions 'for a date', reinforcing the date parameter, but does not compensate for the undocumented lat/lon parameters, leaving their semantics to inference from the tool name.

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 indicates the tool provides sunrise, sunset, and moon events for a given date. While there is no explicit verb, the resource and scope are unambiguous, and the distinction from weather-related siblings like forecast or airquality is evident.

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

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

The description implies usage: if you need sunrise/sunset/moon data, this is the tool. However, it does not explicitly mention when to use it over alternatives or provide any exclusions, making the usage guidance merely implied rather than explicit.

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 valuable behavioral context beyond annotations: it states ownership enforcement, that the row is deactivated (not deleted), and that historical events remain available via recent_alerts. This clarifies the non-destructive nature and side effects. It does not contradict any annotation.

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 highly concise: two sentences, front-loaded with the primary action. Every sentence adds meaningful information (ownership, deactivation, historical data). 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?

For a simple single-parameter tool with strong annotations, the description covers the essential behavior: what it does, ownership constraints, and the non-destructive deactivation with historical data retention. It lacks explicit mention of the response format or error cases, but the output schema is absent and annotations cover idempotency and side effects.

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

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

The schema fully describes the single 'id' parameter ('Subscription id (uuid) returned by subscribe'). The description adds no additional parameter detail beyond referencing 'by id', so with 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It is distinct from the sibling 'subscribe' tool, but does not explicitly differentiate itself from other related tools like 'list_subscriptions' or '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?

The context of use is implied by the action ('Cancel a subscription'), and ownership enforcement is mentioned. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., 'use subscribe to create, list_subscriptions to view, unsubscribe to cancel'), leaving usage to be inferred.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior, but the description adds crucial nuance: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (cover no source). It also details return values (verdict, actual value, citation, reasoning) and the fallback pipeline, which the annotations do not convey.

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

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

Although longer than typical, every sentence adds value: query examples, scope, routing logic, return types, and a critical caller caveat. It is front-loaded with common phrasings and purpose, and the structure is logically organized. No fluff or redundancy.

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

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

With no output schema, the description fully specifies expected outcomes (verdict list, actual value, citation, reasoning) and explains failure modes. For a tool with two parameters and rich annotations, it covers all necessary context: when to use, how it routes, what results mean, and how to interpret edge cases.

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

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

Schema description coverage is 100% with detailed descriptions for both parameters. The tool description adds no additional meaning beyond the schema; it mentions 'exact percent-delta math' but does not elaborate on tolerance_pct beyond what the schema already provides. Thus baseline 3 is appropriate.

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

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

The description clearly states a specific verb (validate) and resource (natural-language claim) against authoritative sources, and differentiates from siblings by explicitly covering two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else). It also distinguishes its scope (fact-checking) from general research tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains how to categorize claims (company-financial vs. other). It also notes that it replaces 4-6 sequential calls, guiding the agent to prefer this tool over composing workflows.

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