Weatherapi

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details: default model is free, BYO key for Anthropic (cost implications), and return structure. It does not contradict annotations.

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

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

The description is concise, consisting of three sentences that efficiently convey the tool's purpose, default behavior, and return values. It is front-loaded with the main action.

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

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

The description covers input (entity, models, optional fields), output (per-model object with score, confidence, signals, raw_response, combined view), and use cases. No output schema exists, so the description adequately explains return values.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default model and the optional API key for Anthropic, which is beyond the schema descriptions. It also clarifies the purpose of the context 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 provides a specific verb-resource combination: 'Probe one or more LLMs' and 'score visibility'. It clearly states the tool's function and distinguishes it from siblings by mentioning use cases like AI-marketing audits and brand checks, which are not covered by other 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 gives explicit use contexts: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not specify when not to use the tool or mention alternative tools for similar tasks, though the sibling list provides potential 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, and non-destructive. The description adds valuable context about routing across 5,462 sources, filling arguments, and returning stable citation URIs, which goes beyond mere annotation repetition. It could disclose potential latency or failure modes but the safety profile is well covered.

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

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

The description is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and organized into clear paragraphs. It is somewhat lengthy but every sentence contributes useful context for such a broad tool. It could be tightened without losing meaning.

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

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

For a tool with no output schema, the description compensates by explaining the return format (structured answer with citations), providing a rich set of examples, and giving clear fallback guidance. Given the tool's complexity and broad applicability, this is a complete and self-sufficient 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% with the primary parameter 'question' and its aliases clearly documented. The description adds no additional parameter semantics beyond what the schema already provides; examples are duplicated in the schema's examples array. The aliases are already listed in the parameter description, so the description adds no extra 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: routing questions to a wide range of verified tools and returning structured answers with citations. It uses specific verbs like 'routes,' 'fills arguments,' and 'returns,' and differentiates itself from siblings (ask_pipeworx_grounded, deep_research) by scope and use case.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH,' 'START HERE for most questions,' and 'Step up only when needed' for alternatives. It lists concrete trigger phrases and examples, and names sibling tools with distinct use cases.

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

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

The description discloses that candidate routing improvements are 'enabled live whenever one is under test' and that results are compared against the stable router, adding behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It also states 'Falls back to nothing — this IS a full working router,' which further clarifies its experimental nature. 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 only four sentences long, front-loaded with the core definition, and each sentence adds necessary context: beta status, current state, usage instruction, and fallback behavior. There is minor redundancy but it is overall efficient and well-structured.

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

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

With no output schema, the description compensates by referencing the exact similarity to ask_pipeworx ('same response shape') and clarifying it is a full working router. It covers beta status, experimental nature, current equivalence to stable, and usage guidance, making it complete for a router tool. The reference to ask_pipeworx covers the response format dependency on the sibling.

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

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

The schema already documents all six parameters as aliases for 'question' with 100% description coverage. The description merely says 'same arguments' without adding syntax, type, or semantic details beyond what the schema provides, so it adds no additional parameter-level 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 it is a 'Beta version of ask_pipeworx: identical universal router' with the same 5,462 tools and response shape, providing a specific verb+resource+scope. It distinguishes itself from siblings by mentioning 'candidate routing improvements enabled live' and the experimental edge.

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 instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and notes 'results are compared against the stable router to decide what merges.' It also clarifies the current state: 'No candidate is active right now... so this currently matches ask_pipeworx exactly,' which gives a clear when-to-use condition and implicitly points to ask_pipeworx for stable alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behaviors: extraction method, refusal return shape with specific refusal_reason enums, and the extra LLM call cost. This enriches the agent's understanding of system behavior 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 packed with essential information in a logical flow: purpose, mechanism, output format, usage guidance, and cost. Each sentence provides unique value, and the structure is front-loaded with the primary differentiator, making it efficient and scannable.

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

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

With no output schema, the description fully describes success return fields ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and error/refusal cases. It also covers usage context and cost, making it self-sufficient for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description adds value by stating the tool automatically 'fills arguments' during routing, clarifying that the agent only needs to provide a natural-language question. This contextualizes parameter usage 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 identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from siblings by emphasizing extraction using ONLY tool result content. It mentions the same routing as ask_pipeworx but with a different output behavior, making it distinct from ask_pipeworx and ask_pipeworx_beta.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and provides specific high-stakes examples. It also gives a when-not-to-use directive ('prefer ask_pipeworx for casual lookups') and names the alternative tool, fully addressing selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by enumerating the specific data fields returned and including an example invocation. This goes beyond what annotations alone convey, though it does not address rate limits or error 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 two sentences: one functional summary and one example. It is front-loaded with the key purpose and wastes no words. Every sentence earns its place.

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

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

For a simple lookup tool with three parameters, good annotations, and no output schema, the description is complete enough. It tells the user exactly what data will be returned and gives a usable example. Minor gaps like default date behavior are already covered by the schema, not 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 description coverage is 100%, so the baseline is 3. The description includes a usage example showing q and dt, which reinforces the schema. However, the schema already thoroughly explains all three parameters, including the nuanced IATA code note for q. The description does not add meaning beyond the schema.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('astronomy data') along with the key output fields (sunrise, sunset, moonrise, moonset, moon phase, moon illumination). This distinguishes it from sibling tools like current, forecast, and marine, which cover other weather domains.

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

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

The description states exactly when to use the tool: to retrieve astronomy data for a given location and date. It provides a concrete example with parameters, making the context clear. It does not explicitly mention when not to use it or name alternative tools, but the purpose is distinct enough that no exclusions are needed.

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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Beyond these, the description adds rich behavioral context: low-confidence resolutions short-circuit with status 'low_confidence_match', closed markets return 'market_closed_or_inactive', wide spreads get tradeability note, cancellation rules are parsed, and fallback mechanisms for news fields are explained. 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 well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the main purpose. However, it is very long (over 1000 words). While the detail is valuable, a more concise version could improve clarity without sacrificing essential 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?

Given the tool's complexity (3 parameters, no output schema), the description is exceptionally complete. It covers response shapes (market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent event extraction, news field fallbacks, safety behaviors, and resolution-rule risk. Every aspect is addressed thoroughly.

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 coverage is 100%, but the description adds significant meaning: it explains the 'market' parameter accepts slug, URL, or question text with examples; 'depth' describes quick vs thorough behavior; 'include_raw' explains the trade-off between summary size and full payloads for post-processing. This adds valuable context beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research) and resource (Polymarket bet with Pipeworx data), and distinguishes from sibling tools like polymarket_arbitrage by detailing its unique functionality (resolving markets, classifying, fanning out to data packs).

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also offers guidance on inspecting the resolver contract (market_match_confidence) before trusting analysis, and explains when to consult alternative tools (e.g., low-confidence matches short-circuit). This is comprehensive usage guidance.

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

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

Annotations already show readOnlyHint, openWorldHint, idempotentHint. The description adds specific data sources (SEC EDGAR/XBRL, FAERS), explains handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). 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 dense paragraph but every sentence adds value. It could be slightly more structured with bullet points for clarity, but it is not overly long. Minor deduction for lack of visual structure.

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

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

Given the complexity of a comparison tool with two entity types, multiple data sources, and sorting, the description covers what the tool does, how it works, and what to expect. It explains return format despite no output schema. Complete enough 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% (both parameters described), baseline 3. The description adds significant value by explaining each enum value ('company' pulls 10-K data, 'drug' pulls FAERS counts) and providing concrete examples for the values array (tickers/CIKs for companies, drug names). This goes far 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 performs side-by-side comparison of 2-5 companies or drugs. It differentiates from siblings by explicitly preferring over sequential single-pack lookups and claims to replace 8-15 lookups. Natural language triggers like 'compare X and Y' make 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?

Provides explicit when-to-use guidance ('ALWAYS PREFER over sequential single-pack lookups'), natural language triggers, and details on what each entity type returns (SEC data for companies, FAERS data for drugs). It contrasts with the sibling entity_profile tool by emphasizing parallel vs. sequential calls.

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 agent knows this is a safe, read-only operation. The description adds the real-time scope and return-field list, but it does not disclose behaviors like API key requirements, response format, or data source beyond the schema's param note about IATA/ICAO.

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 inputs, and includes a concrete example. 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?

With no output schema, the description lists the returned data fields, which is helpful for an agent to know what it will receive. Combined with robust schema coverage and safety annotations, the description is adequate for selecting and calling the tool, though units and response structure are not specified.

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 parameter docs and an example already present. The description adds a condensed summary of location formats and a call example, but this is marginal beyond the schema's structured information.

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

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

The description uses a specific verb/resource ('Get current/real-time weather') and enumerates the data fields (temperature, condition, humidity, wind, UV, AQI), making it clear what the tool does. The 'current/real-time' qualifier distinguishes it from sibling tools like forecast or astronomy.

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

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

The description clearly states this is for current/real-time weather and provides supported location formats plus an example. It implicitly conveys when to use it versus forecast tools, but it does not explicitly name alternatives or state exclusions, so it falls just short of a top score.

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

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

Annotations declare readOnly/openWorld/idempotent, and the description discloses critical behavioral traits beyond these: never-invented gaps[], contradictions[], fetchable citation_uri rules, semantic excerpting, latency ranges, and depth-dependent hop behavior. No contradiction with annotations.

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

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

Long but every sentence earns its place: account requirement first, then purpose, alternatives, output specifics, edge cases, and performance. Front-loaded with the most decision-critical info and structured logically 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 explains the return payload (findings packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It also covers failure modes, latency, and account constraints, making the tool usable without additional context.

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

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

Schema covers both parameters 100%, so baseline is 3. The description adds value by explaining depth implications (hop counts, paid tier, latency) and clarifying that broad questions are fine. It goes beyond schema descriptions, especially for 'question' semantics.

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

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

The description specifies a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in ONE call, then itemizes output. It differentiates from siblings by explicitly naming ask_pipeworx for single lookups and contrasting with open-web search.

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

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

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account prerequisite and fallback for unsigned users.

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 value beyond annotations: it reveals that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' Annotations already mark it read-only and idempotent, and the description aligns with those while adding behavioral details.

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

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

The description is moderately concise and front-loaded with purpose and usage. It contains two substantial sentences covering key points without fluff. Slightly verbose due to listing examples, but overall efficient.

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

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

Given the tool's complexity (6 parameters, no output schema), the description adequately explains the return value (top-N tools with schemas and examples). It does not detail every output field, but the output is self-explanatory. The description provides enough 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 description coverage is 100%, so baseline is 3. The description mentions query aliases but the schema already documents them. No additional semantic meaning beyond what the schema provides for parameters. The description focuses on overall behavior rather than parameter-specific guidance.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb 'find' and the resource 'tools', and effectively distinguishes from sibling tools by explaining it is for browsing/discovering available tools, not for a specific domain like stocks or news.

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 advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists examples of tasks (SEC filings, FDA drugs, etc.) where discovery is appropriate, providing clear usage context without needing 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 indicate read-only, idempotent, non-destructive. The description deepens transparency by detailing data sources, return fields, parallel fan-out, and known limitations (patent soft-fail, name restriction). No contradiction with annotations.

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

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

The description is front-loaded with examples and key directives. While dense, every sentence provides value (sources, return fields, limitations). Could be slightly shortened without loss of clarity.

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

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

For a complex profile tool with no output schema, the description covers main return fields (cik, filings, fundamentals, etc.) and parallel execution. Lacks details on error handling or pagination, but is sufficient for typical use.

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

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

Input schema provides 100% coverage with descriptions for both parameters. The description adds crucial context: value can be ticker or CIK, names not supported (requires resolve_entity). This extends beyond schema detail, though not fully comprehensive for edge cases.

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 full cross-source profile for US public companies with specific examples (e.g., 'Tell me about X', 'research Acme'). It distinguishes itself from sibling tools like resolve_entity and chaining single-pack lookups, providing clear purpose 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?

Explicit guidance: 'ALWAYS PREFER over chaining single-pack...when the user asks for a holistic view.' Also advises to use resolve_entity first if only a name is available. Mentions patents may soft-fail after May 2025, setting 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds what data is returned and the 10-day limit. It does not mention rate limits or API key nuances, but the key behavioral context is present. No contradiction with annotations.

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

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

Two concise sentences, front-loaded with purpose, followed by a relevant example. Every word earns its place; 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?

With no output schema, the description appropriately lists return fields (high/low, condition, rain chance, precipitation, sunrise/sunset) and the 10-day maximum. Combined with rich schema and annotations, the tool is fully understandable for a read-only forecast operation.

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 detailed descriptions for all three parameters. The main description adds no extra parameter semantics beyond the example call, which merely mirrors the schema example. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states 'Get a multi-day weather forecast for a location' and lists specific data (daily high/low, condition, chance of rain, precipitation, sunrise/sunset). This distinguishes it from sibling tools like 'current' or 'astronomy' by focusing on multi-day forecast details.

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 for multi-day forecasts via the example and the word 'multi-day', but it does not explicitly contrast with sibling tools (e.g., 'for current conditions use current') or state exclusions. No when-not-to-use guidance is given.

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 destructiveHint=true and idempotentHint=true, so the description's mention of 'delete' and 'clear' reinforces but doesn't add major new behavioral info. The description adds some safety context ('sensitive data'), but overall the behavioral profile is well-covered by annotations.

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

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

The description is two sentences, front-loaded with the core action, and contains no extraneous words. Every sentence serves a purpose: stating the action, providing usage guidance, and linking to sibling tools.

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 delete tool with one parameter, no output schema, and clear annotations, the description is complete. It explains when to use, what the parameter is, and how it relates to other tools, leaving no gaps.

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

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

Schema coverage is 100%, so the schema already describes the parameter 'key' as 'Memory key to delete'. The description adds no additional semantic meaning beyond what's in the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key. It distinguishes itself from sibling tools 'remember' (store) and 'recall' (retrieve), 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 explicitly states when to use: when context is stale, task is done, or to clear sensitive data. It also mentions pairing with 'remember' and 'recall', providing clear context and alternatives.

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

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

Description adds detail beyond annotations: 'Fetches the page, extracts title/description/key links, emits standard llms.txt markdown format' and 'Output is a single text blob ready to drop at site-root/llms.txt'. No contradiction with annotations (readOnlyHint, destructiveHint false).

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

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

Four sentences, no waste. First sentence states purpose, second explains process, third gives output format, fourth lists use cases. Front-loaded with key 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?

Given simple tool with 2 params, good annotations, and no output schema, description fully covers purpose, behavior, output, and use cases. No gaps.

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

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

Schema covers 100% of parameters. Description adds value by specifying default (25) and max (50) for max_links, and explains output includes key links, supplementing schema.

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

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

The description states clear action ('Generate a production-ready llms.txt file for any URL') and resource (llms.txt for a URL). It distinguishes from diverse sibling tools by focusing on a specific output format and use case.

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

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

Description explicitly lists use cases (getting a client's site indexed, drafting for own project, auditing competitors). However, it doesn't mention when not to use or alternative tools, though no direct siblings exist.

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, destructiveHint. Description adds details about return fields and optional inclusion of inactive subscriptions. No contradictions.

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

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

Two sentences, no fluff. Front-loaded with purpose and returns.

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

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

Complete for a simple list tool with one optional parameter. Covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% for the single parameter. Description does not add to parameter semantics but lists return fields, compensating for the absent output schema.

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

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

Description clearly states it lists the caller's active subscriptions and specifies return fields (id, type, params, etc.). Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No ambiguity with alternative 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?

Annotations mark the tool read-only, idempotent, and non-destructive; the description adds behavioral details such as a 7-day forecast horizon, 6-hour sampling interval, and the specific data fields returned, which usefully extends the annotation-only picture.

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

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

The description is two sentences plus a compact example, front-loading the purpose and providing a concrete usage illustration with zero filler.

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

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

Given the absence of an output schema, the description compensates by listing the marine data fields (wave height, swell, water temp, wind), the forecast window, and a code example, making it reasonably complete for a read-only forecast tool.

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

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

Schema coverage for parameters is 100% with detailed descriptions, and the description only reinforces the example call and the 7-day limit without introducing new parameter semantics, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb phrase 'Get marine/ocean conditions forecast for a coastal location' and enumerates the key fields (wave height, swell, water temperature, wind), clearly differentiating it from the general weather 'forecast' sibling by focusing on marine conditions.

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 sets the context as a marine/ocean forecast for coastal locations, which implies when to use it, but it does not explicitly state exclusions or name alternative tools for non-marine queries, so it falls short of full usage guidance.

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

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

Annotations carry no safety signals (all hints false), so the description must disclose behavioral traits on its own — and it does. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and audience/impact ('The team reads digests daily and signal directly affects roadmap'). It also warns not to paste end-user prompts, which is useful 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?

Purpose is front-loaded in the first sentence, and each subsequent sentence adds practical value (usage, exclusion, content rules, rate limit, quota). It's somewhat long at eight sentences, but only the 'team reads digests daily' clause is arguably motivational rather than strictly operational — still, it contributes to transparency, so the length is justified.

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 (3 params, nested object, no output schema), the description covers everything needed: when to use, when not to use, what to write, caveats about external servers, rate limits, and quota. There are no obvious gaps an agent would need to guess 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 schema already documents all parameters at 100% coverage, so the baseline is 3. The description goes further by giving semantic guidance for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and implicitly explaining the enum values through the bug/feature/data_gap/praise usage mapping. This adds meaning beyond the schema's plain definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' — a specific verb and resource that clearly defines the tool's purpose. It also explicitly distinguishes itself from siblings by being the only feedback-oriented tool in the list, and the 'ONLY for tools served by this Pipeworx connection' clause further sharpens its 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion — 'if the tool came from a different MCP server... file it with that server instead' — and even offers a fallback: '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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. This goes well beyond the annotations.

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

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

The description is a single paragraph but well-structured with a clear lead sentence, bullet-like use cases, and technical details. It could be slightly more concise (e.g., list use cases as a bullet list), but remains efficient 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 the tool has one parameter, no output schema, and rich annotations, the description covers core purpose, window behavior, caching, and privacy. It lacks explicit details on the return format (structure of 'top tools' and 'top packs'), which would make it fully complete.

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

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

Schema coverage is 100% with a single enumerated parameter 'window'. The description elaborates on the semantic difference between shorter and longer windows ('hot right now' vs 'steady-state'), adding meaning beyond the schema's enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a selected window. It uses specific verbs and resources, distinguishing it from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on trending data.

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, confirming canonical tools, checking use case alignment). It implies when to use (hot trends) but does not explicitly state when not to use it, which could improve differentiation from similar 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds significant behavioral context: monotonicity checks, partition checks, fill checks against CLOB depth, semantic anchor, placeholder filters, and response structure. 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 well-structured and front-loaded, but slightly verbose due to detailed technical explanations. Every sentence adds value, but some redundancy could be trimmed for even higher conciseness.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array, partition_check, fill_check), covers all modes, edge cases (placeholder filtering, low similarity pairs), and provides trading safety advice. Comprehensive for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra meaning: explains recommended usage for event vs topic, provides concrete examples of valid values, and outlines the logic behind each mode.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like 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?

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Includes when not to trade (when realizable_edge_pp ≤ 0) and recommends polymarket_fill_risk for custom sizing.

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

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

Description extensively documents behavior: caching at KV level for 1h keyed on knobs, three model families with specific logic, diagnostic output for empty segments, and tradeable-edge filters. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and description adds rich context without contradiction.

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

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

Description is quite lengthy, covering extensive details in dense paragraphs. It is structured with segments, but could be more concise by condensing some technical explanations. While informative, it burdens the agent with reading time.

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

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

Given the complexity with 9 parameters and no output schema, the description is highly complete. It explains top-level response structure, edge metrics, diagnostics, caching, and knobs in detail, leaving little ambiguity for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions. Description adds extra context for several parameters (e.g., explains why min_kelly doesn't filter partitions for min_partition_leg_kelly, mentions zero trading fees but practical slippage for slippage_pp). Not all parameters gain additional meaning, but the added value justifies above baseline 3.

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

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

Description clearly states the tool scans Polymarket markets for opportunities where Pipeworx disagrees with market price, targeting 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by specifying the Pipeworx data source and unique 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?

Provides explicit guidance on when to use ('what should I bet on today') and details on customizable knobs like min_liquidity and max_spread_pp. Lacks direct comparison to all siblings, but context signals list related tools, and description implies use for discovering opportunities rather than executing trades.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent. The description adds behavioral details: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), and limitations (60-day TTL, daily closes). This provides useful context beyond the annotations.

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

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

The description is detailed but well-structured, with the core purpose front-loaded. It includes a clear response section and limitations. However, it is somewhat long and could be slightly more concise without losing 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?

Given the absence of an output schema, the description fully explains the return values (tracked[], expired[], snapshot_dates[]) and their meanings. It also covers limitations and defaults. This provides a complete understanding of 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?

Schema coverage is 100%, so baseline is 3. The description reiterates defaults and constraints (e.g., 'days (lookback, default 14, max 30)') but does not add new semantics beyond the schema. It explains how parameters affect the output, but that is expected.

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: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series tracking rather than current edges.

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

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

The description explicitly states when to use the tool: to understand if an edge is fresh or decaying. It implicitly contrasts with current snapshots by emphasizing historical trends. Although it does not name alternative tools, the niche is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, verdict), and warns about forced directional risk from partial fills. This goes beyond the annotations without contradicting them.

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

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

The description is comprehensive and well-structured with clear sections marked by bold headings. It is longer than average, but every sentence adds value given the tool's complexity. Minor redundancy in listing return fields could be tightened, but overall it is efficiently packed with essential 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?

Despite lacking an output schema, the description thoroughly documents return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers parameter ranges (size_usd clamp 10–1,000,000) and explains the risk profile. The tool's complexity is fully addressed, 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?

Schema description coverage is 100%. The description adds meaning beyond schema by explaining the interplay between 'market' and 'event' modes, the default auto behavior for basket side, and how size_usd is interpreted differently for single-market vs basket. This enriches the agent's understanding beyond the parameter descriptions alone.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes: single-market and basket. It explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) and explains when to use this tool, providing a specific verb-resource pairing.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the risk of partial basket fills converting an arb into an unhedged directional position. It provides clear when-to-use and when-not-to-use guidance with alternatives named.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) and explains conditions under which the tool may not yield tradeable spreads. This provides rich behavioral context.

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

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

The description is thorough but somewhat verbose; it uses bullet-like formatting but could be more concise. Every sentence adds value, but the length could be reduced without losing clarity.

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

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

Given the tool's complexity (3 optional params, no output schema), the description fully covers response fields (prices, spreads, compatibility, temporal alignment, skipped types) and edge cases (e.g., pre-mapped topics often return warnings). The agent has sufficient context to use the tool correctly.

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

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

All parameters have schema descriptions, and the tool description adds further meaning: explaining the two modes, listing the 10 topic macros, and clarifying that explicit tickers override the topic. This goes beyond the schema alone.

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

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

The description explicitly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It differentiates two modes (topic shortcuts vs explicit tickers) and provides response structure, making it clear what the tool does and distinguishing it from siblings like polymarket_arbitrage.

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

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

The description explains when to use (e.g., for checking spreads) and warns about compatibility warnings and temporal alignment, indicating when the tool will produce meaningful results. However, it lacks explicit comparison to alternative tools for similar tasks, such as polymarket_arbitrage.

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, idempotent, non-destructive. Description adds scoping to identifier and pairing info, but no new behavioral traits beyond that.

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

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

Four sentences, each informative and no redundancy. Front-loaded with core action, then use cases and relationships. Highly concise.

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

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

Complete for a simple read tool with one parameter. Covers purpose, usage, scope, and sibling relationships. Output schema not 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?

Schema coverage is 100% but description adds meaning: explains key type, omission behavior, and gives examples (ticker, address). Adds significant value beyond schema.

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

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

The description clearly states it retrieves saved values or lists all keys, distinguishing from siblings like remember and forget. It uses specific verbs and resources.

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 (look up context) and pairs with remember/forget. Explains behavior when key is omitted and scoping to identifier.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that mark_read flags events as read, affecting future calls, and mentions the feed is persisted. 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?

Four to five sentences, each adding unique information. Front-loaded with purpose, then details. No redundant or unnecessary text.

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 5 optional parameters and no output schema, the description covers what the tool returns, filtering options, state management, and alternative access. No gaps.

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

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

Schema covers 100% of parameters with descriptions. The description adds context like filtering by type example ('sec_8k'), ISO timestamp interpretation, and mark_read side effects, providing value beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies return fields (source, citation_uri, etc.), and distinguishes it from the alternative GET endpoint. No sibling tool duplicates this functionality.

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 polling works fine, provides filter examples (type, since), explains mark_read behavior, and points to an alternative access method (GET endpoint) for scripts/dashboards.

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, openWorldHint, and non-destructive. The description adds significant behavioral detail: parallel fan-out to multiple sources, fallback from GDELT to GNews on rate limits/5xx, USPTO soft-failure until reactivated, and structured return format with citation URIs. 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 efficiently structured: common query examples front-loaded, followed by data sources, parameter details, and return format. No redundant sentences. Every sentence contributes meaningful 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?

Despite no output schema, the description fully explains the return structure (changes grouped by source, total_changes count, citation URIs). It covers fallback mechanisms and limitations. For a tool with 3 required parameters and multiple data sources, this is complete and 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?

The input schema has 100% description coverage, but the description adds substantial value: explains that 'since' accepts both ISO dates and relative shorthand with examples, recommends '30d' for typical monitoring, and clarifies that 'value' can be ticker or CIK. This goes beyond the schema definitions.

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 a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes from sibling tool entity_profile, which is used for static profiles. The purpose is unambiguous and well-defined.

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 with common query examples ("What's new with X", "latest on Y"). It directly advises using entity_profile instead for static profiles, and explains fallback behavior between GDELT and GNews. This offers clear context for appropriate tool selection.

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

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

Annotations indicate idempotentHint=true and readOnlyHint=false. The description adds context: key-value pair scoped by identifier, persistent vs 24-hour retention. 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?

Multiple sentences but efficient. Front-loaded with purpose, then usage, then details. No fluff, but could be slightly more concise.

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

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

For a simple store tool with no output schema, the description covers what to store, when, how long, and companion tools. Given context signals and annotations, it is complete.

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

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

Schema has 100% coverage with good descriptions. The description adds value by giving examples for key and emphasizing that value is any text, reinforcing meaning beyond schema.

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

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

The description starts with a clear verb and resource ('Save data the agent will need to reuse later') and gives concrete examples (ticker, address, preference). It also distinguishes itself from sibling tools recall and forget by mentioning them.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides companion usage hints with recall and forget. Also explains scope and persistence (authenticated vs anonymous).

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 safe/read-only/idempotent. The description adds valuable behavioral context beyond that: it discloses that each call cascades through multiple internal endpoints, returns citation URIs, and auto-disambiguates company inputs. This helps the agent anticipate latency and understand the multi-lookup nature.

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 somewhat lengthy but well structured: it opens with practical example queries, then states the core purpose, and provides a clear breakdown of supported types. Every sentence adds value, though it could be tightened slightly. The format is 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 2-parameter tool with no output schema, the description is remarkably complete. It covers input variants, output contents, citation behavior, and internal cascading. The agent can confidently invoke this tool without needing extra documentation about return values or 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?

Although schema coverage is 100%, the description enriches parameter understanding substantially. It explains exactly what value expects for each type: for company, ticker (AAPL), CIK (0000320193), or name; for drug, brand or generic name. It also clarifies the output format per type (e.g., ticker + CIK + company_name + citation URI), 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 clearly states the tool's purpose: resolving a spoken name to a canonical identifier. Example queries like 'What's the ticker for…' and 'find the CIK for…' make the function unmistakable. It distinguishes this from siblings by emphasizing it provides the ID that other tools require as input, and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit guidance on when to use the tool: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools like entity_profile, so it lacks a clear exclusion clause.

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. The description adds value by detailing the probing process using ai_visibility_check, mentioning API key requirements for Anthropic, and specifying the output includes score, confidence, and signal density, which are beyond the annotations.

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

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

The description is well-structured, starting with the core purpose, then explaining the process, and giving a usage example. It is concise enough to be easily scanned but contains all necessary information. Slight reduction could be made, but overall it's effective.

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

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

Given the four parameters (one required), no output schema, and good annotations, the description fairly covers the tool's behavior and return value. It mentions the ranked list with specific fields, but lacks detail on the exact JSON structure, which would be helpful with no output schema. Still, it is sufficiently complete for selection and invocation.

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

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

With 100% schema coverage, the baseline is 3. The description adds the narrative nuance that the first entity is treated as the 'subject,' which is not in the schema. It also clarifies the relationship between models and _apiKey. This adds meaningful context 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, using a specific verb and resource. It distinguishes itself from sibling tools like ai_visibility_check by emphasizing the comparative, multi-entity nature and providing a concrete use case example.

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 indicates when to use the tool (competitive AI-marketing audits) and implies when not to (single entity checks, which would use ai_visibility_check). It could be more explicit about alternatives, but the context and sibling list provide enough 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 indicate safe read operation. Description adds significant behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, sources_failed will list timeouts, and return structure is fully described.

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

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

The description is a single paragraph but front-loads the purpose with a clear summary. It is comprehensive yet efficient, including return structure, ecosystem notes, and error handling without excessive verbosity.

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 block fields, per-advisory details, links, and alternative versions. Also covers partial failures and timing, making the behavior fully transparent.

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

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

Schema coverage is 100% for both parameters. Description confirms default behavior for version and accepts scoped packages, but adds no new information beyond what the schema already provides.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia information. It specifies the verb 'scan' and resource 'dependency', and distinguishes from sibling tools by focusing on package health metrics.

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

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

Explicitly states when to use: when an agent asks about package safety, popularity, size, or cost. Also provides ecosystem limitation (npm only) and directs to deps.dev:version for other ecosystems, giving clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by detailing the embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char windows), character limit (200K with truncation and flagging), and output features (character offsets, similarity scores).

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 efficient and well-structured. It front-loads the core purpose, immediately explains usage context, then provides technical details. Every sentence contributes meaningful information without redundancy. No unnecessary words.

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

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

Despite having no output schema, the description adequately explains return values (top-N passages with character offsets and similarity scores). It covers the 200K char input cap and truncation behavior. All three parameters are fully described. The tool's complexity is moderate and the description 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?

Schema coverage is 100% with all three parameters described. The description adds value by providing examples for the query parameter ('supply-chain risk', 'fiscal year 2024 revenue'), specifying default value and range for limit, and contextualizing the text parameter as 'the document text you already pulled'. This enhances understanding beyond the schema alone.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with other search 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 clearly states when to use: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns relevant passages) and mentions a sibling tool (ask_pipeworx_grounded) for amplification. No explicit when-not, but the condition is unambiguous.

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

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

The description adds significant behavioral context beyond the annotations: required account type, supported event types with examples, delivery channel details including verification and rate limits. The idempotentHint is not explicitly confirmed or contradicted, but 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 efficient and front-loaded with the core purpose and return value. While it contains extensive detail, each sentence adds value. Minor opportunity to tighten without losing clarity.

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

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

The description covers essential aspects but lacks full return value details (e.g., id format, other response fields) and error conditions. Given the tool's complexity and no output schema, additional context on expected response and failure modes would improve completeness.

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

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

The description provides detailed examples and usage guidance for each type-specific params and delivery channels, adding meaning beyond the schema descriptions. Schema coverage is 100%, and the description enhances understanding.

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 'Create' and resource 'proactive monitoring subscription to a live-data event stream', and specifies the return value 'new subscription id'. This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (to create subscriptions) and provides constraints (requires Pipeworx OAuth account, anonymous/BYO cannot persist). It does not explicitly exclude alternatives, but the context of sibling tools provides differentiation.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. The description adds that the tool returns example questions with tool+argument shapes, providing valuable behavioral context beyond annotations.

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

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

The description is somewhat lengthy but well-structured with a clear topic list and usage instructions. Every sentence adds value, though minor trimming is possible.

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

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

For a simple tool with one optional parameter, the description fully covers what it does, when to use it, and what it returns. No output schema exists, but the description explains the return format adequately.

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

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

Schema coverage is 100%, but the description adds meaning by listing the possible topic values and explaining that omitting the parameter yields a full spread. This goes beyond the schema's description.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and 'call', and distinguishes from siblings by being the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and describes how to use the optional topic parameter. While it doesn't explicitly state when not to use it, the context makes it 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?

Adds valuable behavioral context beyond annotations: deactivates instead of deleting, preserving historical events. Aligns with idempotentHint and destructiveHint. No contradictions.

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

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

Two efficient sentences with no fluff. Front-loads the action and provides necessary details concisely.

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 no output schema, the description covers purpose, ownership, side-effect (deactivation), and relation to recent_alerts. Adequate 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% and the schema already describes the 'id' parameter. The description repeats 'by id' and adds context about the id being returned by subscribe, which is helpful but not essential.

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

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

Clearly states the action 'Cancel a subscription by id' and specifies the resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation. Also explains ownership enforcement and deactivation behavior.

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

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

Explicitly says when to use: to cancel a subscription. Ownership enforcement provides context. Does not mention when not to use or alternatives, but the singular purpose is clear given the sibling list.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: it reveals the two processing paths (SEC EDGAR for financials, grounded pipeline for others), the verdict types, and that it returns citations and reasoning. 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 dense yet efficient. It front-loads trigger phrases, then explains usage flow, behavior, and return value. Every sentence provides necessary information without redundancy.

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

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

With two parameters and no output schema, the description fully specifies what the tool does, how it processes claims, what verdicts are returned, and includes citation details. No missing gaps for an AI agent to use correctly.

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

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

Schema coverage is 100%, but the description significantly enriches both parameters. For 'claim', it explains the natural-language nature and gives examples. For 'tolerance_pct', it describes default behavior, bounds, and when to override (hallucination detection). This goes well 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 identifies the tool as a claim verifier with specific examples like 'Is it true that…' and distinguishes it from siblings by detailing the structured SEC EDGAR fast path for financial claims and a grounded pipeline for others. The verb 'validate' and resource 'claim' are 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?

The description states 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains when the structured path vs. grounded path is used, which provides context. However, it lacks explicit guidance on when not to use this tool or mention of alternatives among siblings.

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