Us Iso Grid

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral details: default free model, BYO Anthropic key, cost implications, and return structure (score, confidence, signals, raw_response). 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: first states purpose and default, second details use cases and returns. No fluff, 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?

Despite no output schema, the description explains return values per-model and combined view. Use cases, parameters, and behavioral nuances are fully covered. Appropriate for the tool's complexity.

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

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

All 4 parameters are documented in the schema (100% coverage). The description adds meaning beyond schema: explains default model for 'models', that '_apiKey' is needed for Anthropic, and 'context' disambiguates entities.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs', 'visibility'). It distinguishes the tool from siblings like 'scan_competitor_ai_presence' by focusing on per-model visibility scoring.

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

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

The description states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model and optional Anthropic usage. However, it does not explicitly mention when not to use or compare with sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description doesn't need to restate those. It adds valuable behavior beyond annotations: routing mechanics, argument filling, stable pipeworx:// citation URIs, and one-call efficiency. This is useful 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?

The description is longer than typical, but every sentence carries weight: the opening 'PREFER OVER WEB SEARCH' is a strong directive, followed by scope categories, examples, default behavior, and tiered alternatives. It's front-loaded and well-structured, though slightly verbose.

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

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

For a meta-tool routing across thousands of sources, the description covers purpose, usage triggers, examples, fallback tools, and return format (structured answer with citations). No output schema exists, but the description explicitly mentions the structured answer with citations, making it complete for an agent to assess and invoke.

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

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

The schema has 100% description coverage with the 'question' parameter and its aliases already documented. The description provides examples of valid questions but doesn't add new semantic meaning to the parameters; it re-emphasizes the natural language input, which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states this tool routes questions to 5,462 tools across 1419 verified sources and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description gives explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE', trigger phrases like 'what is' and 'look up', and specific step-up alternatives for grounded answers or broad research. It also notes when not to use it (e.g., breaking-news is already included).

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

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

The description adds substantial behavioral context beyond the annotations: it reveals this is an experimental edge, that candidate routing changes are enabled live only when under test, that no candidate is currently active, and that it does not fall back to another tool. It also states it is a full working router, preventing mistaken assumptions about degraded functionality. No contradiction with the readOnly/idempotent/openWorld hints.

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

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

The description is four sentences, front-loaded with the most important fact (beta variant of ask_pipeworx with identical behavior). It includes specific details like the number of tools and a retirement date, making it somewhat dense, but each sentence contributes unique information and no filler.

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

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

For a variant tool with rich annotations and a complete schema, the description covers all essential context: relationship to the stable router, current status, how to use it, what to expect in terms of routing experiments, and the response shape (same as ask_pipeworx). It leaves no major ambiguity even without an output schema.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for `question`. The description mentions 'same arguments' but does not need to elaborate since the schema fully explains the parameter semantics. This meets the baseline but adds no extra 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 immediately defines the tool as 'Beta version of ask_pipeworx: identical universal router (same 5,462 tools, same arguments, same response shape)', making the purpose and scope explicit. It further distinguishes it from the stable sibling by explaining it carries candidate routing improvements, so the agent knows exactly what this variant does.

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

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

The description gives clear guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies the current no-candidate state, so the agent knows it currently matches ask_pipeworx. It falls just short of naming explicit when-not-to-use scenarios or alternative sibling tools like ask_pipeworx_grounded.

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

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

The description goes well beyond the read-only/idempotent annotations by detailing the extraction-only-from-source behavior, return structure (answer, evidence, confidence, source, fetched_at), explicit refusal reasons, and the extra LLM call cost. This fully discloses behavioral traits and edge cases.

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

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

The description is dense but well-structured, front-loaded with the core purpose, then details on behavior, return structure, usage criteria, and cost tradeoff. Every sentence adds value, and there is no fluff or repetition.

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

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

For a complex tool with no output schema, the description provides a complete picture: routing, extraction method, explicit success and refusal formats, refusal reason taxonomy, use cases, and comparative costs. It fully equips the agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with all six parameters documented as aliases for the question. The description adds no additional parameter semantics, but the schema fully handles this, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies the behavior (extracts answer using only tool result) and distinguishes itself from siblings by name (ask_pipeworx) and by its grounded/refusal capabilities.

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

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

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. This gives clear when/when-not guidance with a named alternative.

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, openWorldHint, idempotentHint, destructiveHint) are already positive, and the description adds extensive behavioral details: fan-out examples, resolver contract, parent event extractor, news fields, safety mechanisms, resolution-rule risk. No contradictions with annotations.

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

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

The description is very long and dense with information, which may overwhelm agents. While front-loaded with the core purpose, subsequent sections on classifiers, fan-out examples, and response shapes are verbose. Could be more concise while retaining key details.

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

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

Given 3 parameters, no output schema, and moderate complexity, the description covers all essential aspects: input formats, depth options, response structure, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. It is comprehensive for agent understanding.

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

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

Schema coverage is 100%, and the description adds meaningful context beyond schema: depth parameter explained (quick vs thorough), include_raw explained (summarized vs full payloads), market parameter formats elaborated. This adds value for correct invocation.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like ask_pipeworx or polymarket_arbitrage, which have different scopes.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers blocking conditions (low confidence, closed markets) but does not explicitly mention when not to use this tool versus alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds contextual behavior: real-time, for today, specific output details (carbon intensity per interval, marginal CO2). No contradictions; description complements annotations.

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

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

Two sentences, front-loaded with purpose and metrics. No superfluous 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?

The tool has one optional parameter, no output schema, but the description explains what the output contains (carbon intensity metrics, marginal CO2). Given low complexity, description is complete enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter 'limit' described in the schema. The description does not add parameter semantics beyond schema, so baseline of 3 is appropriate. Use case context is provided but not parameter-level detail.

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

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

The description clearly states the tool provides CAISO real-time grid carbon intensity with specific metrics (metric tons CO2 per 5-minute interval, marginal CO2 in lbs/MWh) and example use cases. It differentiates from siblings like caiso_demand, caiso_fuel_mix, and caiso_renewables by focusing on carbon intensity.

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 lists use cases ('what is California grid carbon intensity right now', climate-aware load shifting, hourly emissions reporting), implicitly guiding when to use this tool. It lacks explicit exclusion of when not to use or alternative tools, but the sibling names provide context.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint true and destructiveHint false. Description adds behavioral context that it returns real-time data with forecasts, but doesn't detail data source, timezone, or update frequency. 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 essential information (CAISO, real-time demand, forecast). No redundant words; every sentence adds value.

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

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

Given no output schema, the description adequately explains return values (demand series + forecasts). Annotations cover safety. Could mention data granularity explicitly, but overall complete for a simple read-only 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?

Only one parameter 'limit' with description 'Latest N intervals (default 12).' Schema coverage is 100%, and the main description implies 5-minute intervals. The parameter description is adequate but doesn't add significant 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?

Clearly states the tool retrieves CAISO real-time electricity demand vs. forecast for today, specifying return values (5-minute series, day-ahead and hour-ahead forecasts). Distinguishes from sibling tools like caiso_co2 and caiso_fuel_mix by focusing on demand.

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

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

Explicitly lists use cases: 'is California load tracking forecast', peak-demand timing, demand-response triggers. While it doesn't mention when not to use, the specificity provides clear guidance for appropriate scenarios.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds that data is 'real-time for today' and 'timestamped MW values per fuel type', providing useful behavioral context without contradicting annotations.

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

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

Three sentences: first states purpose and content, second specifies return format, third gives example use cases. No unnecessary words, well-structured and front-loaded.

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

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

Given simple tool with one optional parameter and comprehensive annotations, the description covers data source, time frame, fuel types, granularity, return format, and example queries. Complete for agent to understand invocation.

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

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

Schema coverage is 100% with a single optional parameter 'limit' whose description explains default and granularity. Description mentions '5-minute interval' which reinforces schema but adds no new parameter semantics beyond what schema provides.

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

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

Description clearly states the tool returns CAISO real-time grid fuel mix, listing specific fuel types (solar, wind, etc.) and granularity (5-minute intervals). It explicitly distinguishes from sibling tools like ercot_fuel_mix by specifying 'California' and 'CAISO'.

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 provides specific use cases: 'what is California using to make electricity right now', 'solar curtailment today', 'battery contribution this evening.' It indirectly differentiates from siblings like caiso_demand or caiso_co2 by focusing on fuel mix. Could be more explicit about when not to use, but sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds real-time, 5-min intervals, and 'for today' context, which does not contradict annotations and enhances transparency.

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

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

Two sentences cover all essential info: data source, content, use cases. No wasted words, front-loaded with key details.

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

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

For a read-only tool with one param, annotations, and no output schema, the description sufficiently describes the data (sources, granularity, time frame). Lacks explicit return structure (e.g., units, fields), but still mostly 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?

Input schema covers 100% of parameters with a description for 'limit'. The description does not add extra parameter meaning beyond the schema, but schema is adequate. 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 it provides a breakdown of real-time renewable generation in CAISO, listing specific sources (solar, wind, etc.) and noting it is a subset of caiso_fuel_mix focused on zero-/low-carbon sources. This distinguishes it from siblings.

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

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

Explicitly provides use cases ('California renewable share right now', 'duck curve today') and states it's a subset of caiso_fuel_mix, implying when to use the alternative. Strong 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 declare readOnly, idempotent, openWorld, non-destructive. Description adds specifics: pulls latest 10-K data for companies (with fiscal year handling) and FAERS data for drugs, sorted by primary metric, returns citation URIs. 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?

Single paragraph front-loads core use cases and triggers, then efficiently details data sources, sorting, and outputs. No redundant or unnecessary sentences.

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

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

Given no output schema, description explains returns: paired data and citation URIs. Covers parameter use, data sources, and sorting. Could detail output format more, but 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?

Schema coverage is 100%, so baseline is 3. Description enriches both parameters: explains enum values (company vs drug) and gives examples for values (tickers, drug names). Adds context beyond schema.

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

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

Description explicitly states it performs side-by-side comparison of 2-5 entities (companies or drugs) in a single parallel call, with natural language triggers. It distinguishes from sequential lookups by emphasizing efficiency.

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

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

Explicitly advises to prefer this tool over sequential single-pack lookups for comparisons, and provides contextual triggers. Does not name alternative tools, but the guidance is clear and actionable.

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

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

Annotations only provide readOnly/openWorld/idempotent hints. The description adds extensive behavioral context: account and paid-tier requirements, parallel decomposition, findings packet structure, gaps[] never being invented, contradictions[] on standard/thorough, semantic excerpting of large records, citation_uri resolvability, and latency expectations. 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 long single paragraph with many clauses and parentheticals, but it is front-loaded with the account requirement and packs every sentence with meaningful operational detail. While somewhat dense and hard to scan, there is no filler, and the complexity of the tool justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers prerequisites, use cases, alternatives, and performance, making the tool fully actionable for an agent.

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

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

The input schema already documents both parameters with 100% coverage, including detailed enum descriptions for depth. The description adds operational meaning beyond the schema by linking depth:'thorough' to a paid plan, explaining gap-recovery behavior per depth, and giving timing expectations tied to depth choices—helping the agent choose the right parameter value.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1419 structured data sources in one call, with a specific verb-resource pairing and explicit differentiation from the sibling tool ask_pipeworx. It also explains the decomposition/parallel-routing mechanism, leaving no ambiguity about what deep_research does.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data,' and provides specific exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also names ask_pipeworx as the fallback when the account is not signed in, making alternatives very 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 indicate read-only, idempotent, non-destructive behavior. The description adds significant context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This informs the agent about output format and readiness, going 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 concise (~100 words) and front-loaded: first sentence states purpose, then lists use cases, then output format, then when to call. Every sentence adds value; no fluff.

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

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

For a simple discovery tool with 6 parameters (1 required) and no output schema, the description is quite complete. It explains what results contain (schemas, examples) and that they are callable directly. It could mention pagination or error handling, but these are not critical for functionality.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal meaning beyond what the schema provides; it mentions aliases and gives examples, but those are also present in the schema examples. No new semantic details about parameter formats or constraints are added.

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

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

The description clearly states 'Find tools by describing the data or task', which is a specific verb and resource. It distinguishes itself from siblings by listing concrete domains (SEC filings, FDA drugs, etc.) and emphasizing that it returns tool options rather than direct data, unlike specialized tools like ask_pipeworx or deep_research.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, leaving some ambiguity.

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

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

Annotations (readOnlyHint, openWorldHint, etc.) already indicate safe, non-destructive behavior. Description adds context about parallel fan-out across multiple sources and soft-failure of patents API, though could better highlight possible failures.

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 thorough but lengthy and mixes examples, instructions, and technical details in one paragraph. Front-loads key information well but could be 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?

Given no output schema, the description fully explains return values (cik, company_name, recent_filings with URIs, fundamentals fields, patents, news, LEI). Covers edge cases like patents soft-failure.

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 params. Description reinforces that 'type' must be 'company' and 'value' must be ticker or CIK, not name. Adds value beyond schema.

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

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

Description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and fields. Differentiates from sibling 'resolve_entity' by noting name resolution requirement.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use 'resolve_entity' first if only a name is available.

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 safety, but description adds valuable behavioral details: returns 5-minute snapshot and monthly installed capacity, enabling percent-of-installed computation. No 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?

Three concise sentences, front-loaded with key information (Texas, fuel types, time resolution), no wasted words.

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

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

Lacks output schema but description covers return data fully: fuel types, MW, snapshot, installed capacity, and example queries. Complete for a 0-param tool with strong annotations.

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?

No parameters (0 params, 100% coverage), so baseline 4. Description adds meaning beyond empty schema by explaining the output and derived computations.

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

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

The description clearly states the tool provides ERCOT real-time grid fuel mix with specific fuel types and data frequency, distinguishing it from siblings like ercot_supply_demand.

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 example queries but lacks explicit when-not-to-use guidance or comparison with other regional fuel mix tools like nyiso_fuel_mix.

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, idempotent, and non-destructive. The description adds that it returns hourly capacity, current demand, load forecast, and the time range (recent day + today), providing useful behavioral context beyond the annotations.

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

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

The description is two sentences: the first states what the tool does, the second gives use cases. It is concise, front-loaded, and contains 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?

Given no parameters and no output schema, the description provides sufficient context on data content and usage scenarios. However, it lacks exact output format details (e.g., JSON structure, timezone), leaving minor ambiguity.

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

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

The tool has zero parameters, so schema coverage is 100%. The description explains what data is returned, which adds value beyond the implicit schema. Baseline for no parameters is 4.

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

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

The description explicitly states it provides ERCOT real-time supply vs. demand with hourly capacity, current demand, and load forecast. It clearly distinguishes from siblings like ercot_fuel_mix by focusing on supply/demand rather than fuel mix.

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

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

It provides explicit use cases such as checking reserve margin or emergency-alert proximity during heatwaves, which guides when to use. It does not, however, explicitly mention when not to use or suggest sibling alternatives.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false. Description confirms deletion and adds context about clearing sensitive data, complementing annotations.

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

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

Three brief sentences, front-loaded with action, followed by usage guidance. No fluff.

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

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

Simple one-parameter tool with good annotations. Description covers purpose, usage, and related tools completely.

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

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

Schema coverage is 100%. Description does not add extra meaning beyond 'Memory key to delete' in schema.

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

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

Specific verb 'Delete' and resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall' by mentioning them.

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

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

Explicit when-to-use scenarios: stale context, task done, clear sensitive data. Also suggests pairing with remember and recall.

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 a safe, non-destructive, idempotent operation. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard markdown format, beyond what annotations provide.

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

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

The description is concise, front-loading the core functionality, then output format, then use cases. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully explains the output format (single text blob ready for site-root/llms.txt). It covers purpose, process, and output adequately for a tool with two parameters.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context on what extraction occurs (title, description, key links) and that max_links defaults to 25, max 50, enriching the parameter meaning.

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

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

The description clearly states the tool's action: generating a production-ready llms.txt file. It specifies the verb 'generate' and the resource 'llms.txt', and distinguishes itself from sibling tools by focusing on a unique output format.

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

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

The description provides explicit use cases (e.g., indexing clients' sites, drafting for own project, auditing competitors) which guide when to use the tool. It does not explicitly exclude alternatives, but the context is clear.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying that it returns only active subscriptions (unless the parameter is used) and lists the returned fields, providing useful 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?

Two sentences: first states purpose and output, second gives usage guidance. Every word is necessary; no filler or repetition. Highly efficient.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose, return fields, and usage context, making it complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with one boolean parameter already well-documented. The description does not mention the parameter or add additional meaning, so it meets the baseline for high coverage.

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

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

The description uses the specific verb 'List' and resource 'subscriptions', clearly stating it returns the caller's active subscriptions with listed fields. This distinguishes it 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?

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context for when to use it, though it does not explicitly state when not to use it.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already convey safety and idempotency. The description adds value by specifying 5-minute interval data and the most recent published day. No contradictions.

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

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

The description is only two sentences, front-loading the core purpose and then usage. Every word is necessary; no wasted 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, data content, and usage. It could mention return format more explicitly, but the mention of 'MW per 5-min interval' suffices.

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 description coverage, the description adds the default value ('defaults to yesterday') and format hint, going beyond the schema's definition. This is helpful for an agent.

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

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

The description clearly states the tool provides NYISO real-time grid fuel mix for the most recent published day, listing all fuel types and units (MW per 5-min interval). It distinguishes from sibling ISO fuel mix tools (caiso_fuel_mix, ercot_fuel_mix) by specifying 'New York' and from nyiso load tools by focusing on fuel mix.

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

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

The description explicitly says 'Use for New York grid mix yesterday, NYC clean-energy progress tracking,' providing clear usage context. It does not explicitly state when not to use or list alternatives, but the context is sufficient given the sibling tool names.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable details: returns data for 'most recent published day,' interval (5-min), and breakdowns by zone, which goes beyond annotations.

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

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

The description is front-loaded with key purpose, lists zone examples, and explains return values. Every sentence adds value; no fluff.

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

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

Despite no output schema, the description details return fields (LBMP, losses, congestion) and time resolution (5-min). The tool is simple with two optional parameters, and the description covers all necessary context for proper 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?

Both parameters (date, zone) are fully described in the schema, and the description adds context: date defaults to yesterday (today's file may not be published), zone is optional with default all 11 zones. This enriches 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 retrieves NYISO zonal LMP data for the most recent published day, broken down by load zone. It specifies the return values (LBMP, marginal cost of losses, congestion) and distinguishes from sibling NYISO tools by emphasizing zones and LMP.

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

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

The description provides clear use cases: 'Use for NY wholesale electricity prices, zonal congestion analysis.' However, it does not explicitly exclude scenarios or mention alternative tools, though siblings are listed separately.

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 that data is per 5-minute interval and for the most recent published day, providing useful temporal 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?

Three sentences: first explains what the tool returns, second lists zones, third gives use cases. Front-loaded with essential info, no fluff.

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

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

Given two simple optional parameters and no output schema, the description covers data granularity (5-min intervals), scope (zonal), and use cases. Could mention number of intervals per day, but not critical.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explicitly listing all valid zone values (CAPITL, CENTRL, etc.) and clarifying that date defaults to yesterday, which the schema also notes but the description reinforces.

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

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

The description clearly states the tool provides NYISO actual zonal load in MW per 5-minute interval for the most recent published day, listing all 11 zones. This distinguishes it from sibling tools like nyiso_fuel_mix and nyiso_lmp_zonal.

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 suggests uses: 'NY zonal demand analysis, peak-time identification, NYC load profile vs. upstate.' While it doesn't list when not to use, the context is clear enough for selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that data is per zone in MW and for the most recent published day, which provides useful behavioral context beyond the annotations.

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

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

Two sentences: the first defines the tool's output, the second gives two clear use cases. Extremely concise with no wasted words or redundant information.

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

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

Given the low complexity (2 optional parameters, no output schema, comprehensive annotations), the description covers the key aspects. It could have mentioned the output format (e.g., table) but is largely complete for a simple 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?

Both parameters have full descriptions in the input schema (100% coverage). The description does not add significant new semantics beyond 'per zone' which is already implied by the zone parameter. Baseline 3 is appropriate.

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

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

The description clearly states that the tool provides NYISO load forecast for the most recent published day, per zone, in MW. It explicitly distinguishes from the sibling tool 'nyiso_load' by mentioning forecast vs. actual 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 specifies use cases: 'what does NYISO expect demand to be today' and 'forecast-error tracking vs. nyiso_load'. This provides clear context for when to use the tool, though it does not explicitly exclude other uses.

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

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

Annotations are all false and thus convey no behavioral constraints, so the description carries the burden. It discloses a rate limit (5 per day), states it's free and doesn't count against quota, and notes the team reads digests daily. This context is useful and goes beyond schema. However, it doesn't describe what happens after submission (e.g., no confirmation response), which is a minor gap.

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 wordy (8 sentences) but every sentence serves a purpose: defining scope, usage, exclusions, content guidance, rate limits, and cost. The key info is front-loaded ('Tell the Pipeworx team...'). There is minor redundancy ('ONLY for tools served...' and 'Not sure? Pipeworx tool names are the ones this connection lists'), which prevents a 5, but it remains well-structured and readable.

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

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

Given the tool's complexity (3 params, nested context object, enum type), the description fully covers selection criteria, use cases, exclusions, content expectations, and constraints. The schema covers all parameter details, and there is no output schema to explain. The description leaves no significant questions about when or how to invoke this tool, making it contextually complete.

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

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

Schema description coverage is 100%, so the baseline is 3 due to schema handling parameter details. The description adds extra guidance on how to fill parameters: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This is valuable for message and context, raising the score above baseline but not to 5 because the description doesn't directly elaborate on individual parameter semantics (the schema already covers those well).

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and scope (feedback about tools), and distinguishes it from siblings by covering bug reporting, feature requests, and praise. The 'Use when' phrasing maps exactly to the schema's type enum, making selection 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?

Provides explicit when-to-use guidance: bug, feature/data_gap, praise. It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs to file with a different server if the tool is from another MCP. This prevents misuse and directs to alternatives, exceeding basic 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 indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: data derivation ('CF analytics-engine'), no PII, caching window (5min-1h), and output structure. No contradictions.

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

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

The description is a single paragraph, front-loaded with purpose. Every sentence adds value: purpose, use cases, data origin, privacy, caching. No superfluous 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?

Despite no output schema, the description specifies what is returned (top tools, packs, call volume). It also explains data source, privacy, and caching. For a simple tool with one optional parameter, this is fully informative.

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?

Only one parameter 'window' with full schema coverage (enum, description). The description adds context for window choice ('shorter windows surface what's hot right now; longer windows show steady-state demand'), going beyond the schema's basic description.

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

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

The description clearly states the tool returns top tools, packs, and call volume over windows. It uses specific verb ('Returns') and resource ('top tools, top packs, and total call volume'). It distinguishes from siblings like ask_pipeworx by focusing on aggregated trending data rather than direct queries.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). It does not mention when not to use or compare to siblings, but the context signals suggest it's a distinct analytical tool.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing internal logic: monotonicity checks, partition_sum checks, fill check with CLOB depth, semantic anchor for similarity, partition filter. It also explains the response structure and trade signals. 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 detailed and informative but somewhat verbose, spanning multiple paragraphs. It is front-loaded with the core purpose but includes many technical details. While every sentence adds value given the complexity, a more streamlined version could improve conciseness.

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

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

Given the tool's complexity (2 parameters, no output schema, intricate internal behavior), the description is remarkably complete. It covers all modes, input requirements, internal checks, response structure, fill verification, and even references a related tool (polymarket_fill_risk) for custom sizing.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds significant context beyond the schema: it explains the modes, acceptable input formats, and how each parameter triggers different behavior. Examples are given ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal').

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 defines three distinct modes (no args, event, topic) and uses specific verbs ('find', 'call', 'pass'). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided for when to use each mode: no args for trending scan, event for per-event check, topic for cross-event scan. It recommends event mode for specific markets and explains why cross-event mode is beneficial. However, it does not explicitly state when not to use the tool or list 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: cache behavior (1h KV, knob-keyed), segment logic, Fed exclusion, diagnostic feedback, and edge calculation details. No contradictions found.

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 with valuable information and well-structured with numbered segments and bullet points. However, some details (e.g., exact α values for sports, historical gate values) are extraneous for agent usage and could be streamlined 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 (9 params, no output schema), the description is exceptionally complete. It explains output structure (by_segment, diagnostics, fed_note), caching policy, filtering knobs, and edge case handling (e.g., why Fed bets are excluded). No gaps identified.

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% (all 9 parameters described). The description adds significant meaning beyond the schema, e.g., explaining min_kelly skips small opportunities, slippage_pp accounts for bid/ask, and min_partition_leg_kelly applies only to per-leg Kelly, compensating for schema limitations.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly targets the use case 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage by focusing on model-driven and structural arbitrage opportunities without manual paging.

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

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

The description provides clear context for when to use the tool (discovering betting opportunities) and details filters like min_liquidity, max_spread_pp, and category_filter. However, it does not explicitly state when not to use it or compare directly to sibling tools, leaving some ambiguity for the agent.

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

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

Provides extensive behavioral context beyond annotations: explains response format, limits (60-day TTL), decay computation, and interpretation of edge_pp_net sign. No contradictions with annotations.

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

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

Well-structured with clear sections for response and limitations, but somewhat verbose; could be trimmed without losing 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?

Comprehensively covers return values, parameter effects, edge cases, and limitations despite lacking an output schema. Sufficient for an AI agent to understand the tool's capabilities.

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

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

Adds context about snapshot gaps and default values beyond the input schema, which already has 100% coverage. The description reinforces but does not significantly extend parameter meaning.

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

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

Clearly states it tracks edge persistence and decay over time, answering a specific question. Distinguishes from sibling polymarket_edges by focusing on historical telemetry.

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?

Implicitly suggests when to use (to assess edge longevity) but does not explicitly name alternatives or when not to use. Context from sibling tools hints at 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=true and idempotentHint=true, so the description does not need to repeat safety traits. However, it adds valuable operational behavior: walking the order-book ladder, returning specific fields like slippage_pp and forced_directional_risk, and warning about partial basket fills. This supplements the annotations effectively.

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 purpose and uses clear section labels (SINGLE-MARKET, BASKET) for scannability. While it is relatively long (~150 words), every sentence adds essential detail. Minor redundancy could be trimmed, but overall it is well-structured.

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

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

For a tool with 4 parameters and no output schema, the description fully enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs). It also explains the risk of partial fills and directional positions. Given the complexity, this is a complete 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%, so the baseline is 3. The description adds context beyond the schema by explaining the dual-mode operation (market vs event), the auto-detection of basket direction, and the interpretation of size_usd for single-market vs basket. This extra explanation raises the score.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check' against live order-book depth, and distinguishes between single-market and basket modes. It also explicitly relates to sibling tools like polymarket_arbitrage and polymarket_edges, making its purpose distinct.

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

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

The description gives explicit usage instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the consequences of not using it (unhedged directional position), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint=true, and the description adds detailed behavioral context: response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and failure scenarios. 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 and front-loaded with purpose, but the safety section is somewhat verbose. Still, every sentence adds value. Just slightly above average in conciseness.

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

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

Given no output schema, the description thoroughly explains the response format including leg-by-leg prices, spreads, safety fields, and their meanings. It covers all necessary context for an agent 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?

Schema description coverage is 100%, and the description enriches each parameter with context: topic values are listed, explicit parameters are explained with examples, and their relationship to modes is clarified.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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 explains two modes (topic and explicit) and provides safety fields with compatibility warnings, guiding when to use and when not. It warns that most pre-mapped topics may return warnings, setting appropriate 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context (scoping to identifier like anonymous IP or account ID, and pairing with other tools) that goes beyond the annotations. No contradictions.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. 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?

Given the simple tool (1 optional param, no output schema), the description completely covers its purpose, usage, behavioral traits, and relationships with sibling tools. Annotations provide safety profile, so no further behavioral info is needed.

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

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

Schema covers 100% of parameters. The description adds meaning by explaining the effect of omitting the key ('list all saved keys') and the purpose of the key (to retrieve a previously saved value). This adds value 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 uses specific verbs ('Retrieve' and 'list') and clearly defines the resource (values saved via remember, or all saved keys). It distinguishes itself from sibling tools like remember and forget by explicitly mentioning them. The purpose is unmistakable.

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

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

The description states when to use the tool ('to look up context the agent stored earlier') and explicitly mentions pairing with remember and forget. While it does not include explicit when-not-to-use instructions, the context is clear enough for effective selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context by explaining that setting mark_read:true flags events as read, affecting subsequent calls. This is a benign side effect that is idempotent, and the description is transparent about it.

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 tight three-sentence paragraph. It front-loads the primary purpose in the first sentence, details return fields and filtering in the second, and adds behavioral notes and alternative access in the third. Zero waste.

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

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

The description explains return fields (source, citation_uri, payload) and the key mark_read side effect. It also mentions polling is acceptable and provides an alternative endpoint. For a tool with 5 parameters and no output schema, this is quite complete, though pagination details are absent.

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 reinforces parameters by giving an example for type ('sec_8k') and explaining mark_read behavior, but adds limited new meaning beyond what the schema provides.

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

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

The description clearly states the action 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on retrieving alert events, and details filtering by type and since, making the purpose highly specific.

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

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

The description provides usage context by noting 'Polls work fine' and offers an alternative access method via a URL. While it doesn't explicitly contrast with other tools, it gives clear context for when to use this tool, including examples for filtering. Slight lack of explicit 'when not to use' prevents a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral details: fans out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and structure of returns (changes[] grouped by source, total_changes, citation URIs). No contradictions.

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

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

Description is dense but efficient, front-loading purpose with example queries, then detailing sources, parameters, and return format. No redundancy, though slightly long; could benefit from bullet points for readability.

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

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

Given the tool has 3 simple parameters, no output schema, and no nested objects, the description provides sufficient context: explains data sources, return structure (changes[], total_changes, URIs), and known limitations (USPTO soft-fail). Competent for an AI agent to invoke.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description adds further guidance: examples for since (ISO date and relative shorthand, recommended '30d'), notes type only supports 'company', and gives examples for value (ticker or CIK). Provides extra clarity beyond schema.

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

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

The description clearly states the tool retrieves recent changes for a company (e.g., filings, news, patents) within a time window, using example queries like 'What's new with X' and explicitly distinguishing from sibling tool entity_profile which provides static profiles.

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

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

Provides explicit context for when to use this tool (change feed within a window) and when to use entity_profile instead (static profile regardless of window). Recommends typical since values ('30d' or '1m'), but could be more precise about when not to use this tool (e.g., for real-time news).

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 behavioral context beyond annotations: it explains persistence (authenticated users get persistent memory, anonymous sessions last 24 hours) and that it's a key-value store scoped by identifier. Annotations already indicate idempotentHint=true and readOnlyHint=false, and the description is consistent.

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 (4 sentences) and front-loaded with the core purpose. Every sentence adds meaningful 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?

The description covers purpose, usage, persistence behavior, and pairing with sibling tools. While it doesn't describe the return value or error conditions, the tool's simplicity and lack of output schema make this acceptable.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description adds examples of key and value content (e.g., 'subject_property', 'findings'), which is helpful but not substantial 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 ('Save') and resource ('data'), clearly states the purpose is for reuse across conversations/sessions, and distinguishes from related tools (recall, forget) by mentioning them as companions.

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 context for when to use ('when you discover something worth carrying forward') and lists the companion tools (recall, forget). It lacks explicit 'when not to use' guidance, but the positive usage is clearly articulated.

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 read-only/idempotent annotations, the description discloses internal cascade behavior, return payloads (ticker, CIK, RxCUI), citation URIs, and auto-disambiguation for company inputs. This provides substantial operational context that the annotations do not convey.

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

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

The description is front-loaded with relatable example queries and a clear definition. It then provides structured details for each supported type. While slightly long, every segment serves a purpose (inputs, outputs, citation info) and there is no redundancy.

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

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

With no output schema, the description thoroughly explains return values and behavior. It covers all aspects needed for correct use: when to use, what types are supported, what inputs are accepted, what outputs to expect, and edge-case behavior (auto-disambiguation). The internal cascade note also helps set performance expectations.

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

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

Schema coverage is 100% with enum and value descriptions, so the baseline is 3. The description adds real value by explaining what each type returns (e.g., company returns ticker+CIK+company_name, drug returns RxCUI+ingredient+brand) and gives concrete examples (AAPL, CIK format) that go beyond the schema's examples.

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

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

The description explicitly states the tool maps a user-spoken name to the canonical/official identifier required by other tools, with example queries ('What's the ticker for…'). It clearly distinguishes itself from siblings by positioning as the first stop when you have a name but need an ID, and the supported types (company/drug) are enumerated.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces 2-3 manual lookups, implying when it's efficient to use. This is a clear when-to-use directive with no ambiguity.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description reveals it internally calls ai_visibility_check for each entity, outputs a ranked list with score, confidence, signal density. No contradictions.

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

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

Three sentences with no wasted words. Clear structure: what, how, utility, output. Highly efficient.

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

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

Covers purpose, mechanism, output format, and example usage. Lacks explicit limitations or error conditions, 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?

Schema coverage is 100%, and the description adds key semantics: first entity is the 'subject', context disambiguates common names. This adds value beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs ('compare', 'probes', 'ranks'). It differentiates from sibling 'ai_visibility_check' by being a multi-entity comparison.

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 context for use ('competitive AI-marketing audits') and an example question, implying it is for multi-entity comparisons. It does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds that tool fans out across deps.dev and bundlephobia, mentions potential 5-30s delay on first measurement, and that partial failures degrade gracefully with sources_failed in response.

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?

Reasonably concise; front-loaded main purpose and then details. Some redundancy but generally 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?

No output schema, so description must describe return values. It does: summary block, per-advisory detail, links, alternative versions. Also covers ecosystem scoping and graceful degradation.

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: package description notes scoped packages accepted, version defaults to latest. Description adds minimal extra 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?

Clearly states the tool does a composite check for adding an npm package, covering license, advisories, version history, and bundle size. Distinguishes from sibling tools which are mostly unrelated.

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

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

Explicitly says use when agent asks about safety, popularity, size, or cost of adding a package. Also mentions ecosystem limitation (NPM only in v1) and where to go for other ecosystems.

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 safe read-only, but description adds concrete technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. This goes beyond annotations and fully discloses 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?

Two well-structured paragraphs: first front-loaded with purpose and key benefit, second with technical details. No extraneous sentences; every sentence adds value.

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

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

Despite no output schema, the description covers input constraints (200K chars), technical setup, and return structure (passages with offsets and scores). Sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for each param, so baseline is 3. Description adds meaningful examples for 'query' and clarifies 'text' as document text, but does not introduce new constraints. Slight improvement justified.

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 semantic search inside a fetched record with specific examples (SEC 10-K, article) and distinguishes from sibling tool ask_pipeworx_grounded, showing a specific verb and resource.

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?

Explains when to use (record too big for prompt), what it achieves (saves context, returns relevant passages with offsets), and pairs with a sibling tool. No explicit when-not, but the context is clear.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context such as the requirement for a Pipeworx OAuth account, SMS rate limits (10/day), and the always-on feed. No contradictions with annotations.

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

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

The description is lengthy and dense, packing many details into a single paragraph. While all information is valuable, it could be better organized with sections or bullet points for readability.

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

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

Given the tool's complexity (multiple subscription types, nested parameters, three delivery channels, and no output schema), the description covers all essential aspects. It explains each type's parameters and delivery channel requirements 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?

Schema coverage is 100%, yet the description enriches every parameter with concrete examples and usage details (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'), surpassing what the schema provides.

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

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

The description clearly states the tool's action ('Create a proactive monitoring subscription to a live-data event stream') and resource ('subscription'), and uniquely positions it by noting the result ('Returns the new subscription id'). It is distinct from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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 specifies when to use this tool ('Requires a Pipeworx OAuth account') and provides context for supported types and delivery channels. However, it does not explicitly state when not to use it or offer alternatives among siblings.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive. Description adds that it returns dynamic examples from the live catalog, implying content may change over time. No negative behaviors disclosed, which is appropriate given 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?

Description is comprehensive but slightly long. It is front-loaded with purpose and alternative phrasings, every sentence adds value. Could be more concise, but not overly verbose.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, return content, and context. No gaps for an agent to understand when and how to call it.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the use of the topic parameter with examples and how it focuses results, going beyond the schema description.

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

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

Description clearly identifies the tool as an onboarding entry point that returns suggested questions, distinguishing it from sibling tools by stating it should be used first when the user doesn't know what Pipeworx can do. It covers multiple phrasings and specifies the output (category-bucketed examples with tool calls).

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 (first when unsure what to ask, to learn meta-tools) and when to pass topic argument. Implicitly excludes advanced users who already know what they want, but does not explicitly mention alternatives. Clear context for usage.

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

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

Discloses deactivation behavior (not deletion), complementing annotations. No contradiction with readOnlyHint=false, destructiveHint=false, idempotentHint=true.

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

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

Two sentences, front-loaded with action, no fluff. Every part 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 mutation with one parameter and no output schema, the description covers purpose, constraint, and side effect. Lacks error handling details but sufficient for typical usage.

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

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

Schema already describes the single parameter (id) with origin (returned by subscribe). Description adds no additional semantic 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?

Title and description clearly state the action (cancel) and resource (subscription by id). Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement ('only cancel your own subscriptions') providing a clear usage condition. Lacks explicit when-not-to-use or alternatives, but sufficient for context.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the two processing paths, exact percent-delta math for financial claims, and the return verdict types (confirmed, refuted, etc.) with citations. 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 a single dense paragraph but is front-loaded with natural-language examples that mimic user queries. It efficiently covers the tool's purpose, two processing paths, and return value. Every sentence adds value; no redundant repetitions. Minor improvement could be breaking into sub-sections for readability.

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

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

Given the tool's complexity (two parameters, no output schema, but rich annotations), the description provides sufficient context: it explains the input format, two processing paths, return verdicts, and efficiency gains over multiple calls. It covers what an agent needs to decide when to invoke this tool.

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

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

Both parameters have full schema descriptions (100% coverage). The description adds extra meaning: it explains that 'claim' is natural-language and gives examples, and that 'tolerance_pct' overrides the default implied by wording. This enriches the schema without being redundant.

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 that the tool verifies natural-language factual claims, distinguishing between company-financial claims (using SEC EDGAR) and other claims (grounded pipeline). The verb 'validate' and resource 'claim' are specific, and the tool is distinct from sibling tools like caiso_demand or bet_research which target specific 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It outlines two processing pathways (financial vs other) but does not explicitly exclude cases where a sibling tool like 'caiso_demand' would be more appropriate, though the sibling names imply alternative tools for specific data.

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