Entso E

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds no extra behavioral context beyond stating it returns 'actual generation per production type per hour.' With annotations covering safety, this is adequate but not enriched.

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

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

The description is a single sentence, concise and front-loaded with key information. However, it could expand slightly on parameter details without becoming 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?

Given the tool has 3 required parameters and an output schema, the description minimally states the data returned. It does not address timezone, granularity, or handling of missing types, but the presence of an output schema reduces the burden.

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 only 33% (only 'area' has a brief description). The tool description does not explain the format or constraints of period_start and period_end (e.g., YYYYMMDDHHMM), relying solely on schema examples. It adds little value beyond the schema.

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

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

The description clearly states the tool retrieves actual generation per production type per hour, listing examples like solar, wind, nuclear. This distinguishes it from siblings like actual_load (total load) and installed_capacity (capacity).

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

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

The description implies usage for hourly generation breakdown by type, but it does not explicitly state when to use this tool versus alternatives or any exclusions. No guidance on prerequisites or context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe, read-only tool. The description adds that the data is 'measured' consumption per hour, reinforcing the non-mutating nature. 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 sentence of 11 words conveys the tool's essence with no redundant information. Every word serves the purpose.

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

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

Given the availability of an output schema and clean annotations, the description is nearly complete. It could mention that the data is historical or real-time, but the core information is present.

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 33% of parameters have schema descriptions (area). The description does not clarify the format for period_start and period_end, which are dates/times (examples show YYYYMMDDHHmm). It mentions 'per hour' but does not explain expected string formats or behavior.

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 measured electricity consumption per hour for a bidding zone in MW. This distinguishes it from sibling tools like actual_generation_per_type (generation) and cross_border_flow (flows).

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

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

No explicit when-to-use or when-not-to-use guidance. While the purpose is clear, there is no mention of alternatives (e.g., use actual_generation_per_type for generation data). Usage context is implied but not stated.

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. Description adds that the tool makes external API calls (Anthropic) when a key is provided, and returns per-model data. No contradictions; however, rate limits or cost implications beyond BYO key are not mentioned.

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

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

Two sentences deliver essential information without waste. Front-loaded with action and output, followed by supporting details. No redundant phrases.

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

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

Given 4 parameters and no output schema, the description adequately covers return structure ('per-model {score, confidence, signals, raw_response} + combined view'). Could specify that output is JSON, but overall sufficient for a read-only information tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful context: explains the default model, that _apiKey enables Anthropic queries, and that context helps disambiguate entities. This goes beyond the schema's property descriptions.

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

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

Description uses specific verb 'probe' and resource 'LLMs' to define the tool's action: scoring visibility (0-100) per model for a business/brand/product/topic. It clearly distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring rather than broader scanning.

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

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

Explicit use cases are provided: AI-marketing audits, pre-launch brand checks, competitive monitoring. It specifies default model and requirement of BYO API key for Anthropic. Though no explicit when-not-to-use, the context is clear enough for an agent to decide relevance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it routes to one of 5,724 tools, fills arguments, and returns stable pipeworx:// citation URIs — beyond what annotations provide. It does not mention latency or rate limits, but the operation is clearly non-destructive and the description is consistent with the annotations.

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

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

Despite its length, every sentence earns its place. It opens with a strong directive ('PREFER OVER WEB SEARCH'), scopes the tool accurately, provides triggers and examples, and closes with clear escalation paths. The information is front-loaded and logically ordered, with no redundancy.

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

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

For a single-question tool with no output schema, the description covers everything an agent needs: what it does, when to use it, how to format the question, what to expect in the response (structured answer with citation URIs), and how it differs from alternatives. The inclusion of triggers and examples makes it fully self-sufficient.

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

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

Schema coverage is 100%, but the description enhances the 'question' parameter by explaining it accepts natural language, listing all aliases (query, q, prompt, text, input), and providing three concrete examples. This adds semantic richness beyond the schema's generic description of the required parameter.

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

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

The description states a specific verb (ask) with a clear resource (Pipeworx) and explicitly scopes it to authoritative structured data with citations, including a detailed list of domains (SEC, FDA, FRED, etc.). It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases, so an agent can immediately tell it apart.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions', 'Use whenever the user asks...'), gives concrete triggers like 'what is', 'look up', 'find', and enumerates examples. It also states when NOT to use it (step up to grounded or deep_research for specific needs), making routing crisp.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that candidate routing improvements are enabled live when under test, that no candidate is active as of a specific date, that the behavior currently matches ask_pipeworx exactly, and that it is a full working router with no fallback. This is valuable operational 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?

Four sentences front-load the identity and sibling relationship, then give current status and usage direction. Every sentence contributes, and the structure makes the experimental nature immediately clear 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?

For a beta alias of a known sibling, it covers the essential context: same arguments and response shape, current state, usage intent, and comparison behavior. It relies on ask_pipeworx for the actual response contract, and with no output schema a slightly more self-contained description could be marginally better.

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

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

The schema already documents all parameters with 100% coverage, including the aliases for question. The description adds no parameter-specific meaning, which is acceptable because the schema carries the full burden; baseline 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 identifies the tool as a beta version of ask_pipeworx and defines it as a universal router with the same 5,724 tools, arguments, and response shape. It also differentiates it from the sibling ask_pipeworx by the live candidate-routing improvements, so an agent can tell what it is and how it differs.

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

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

It explicitly names ask_pipeworx as the sibling stable router and says to use this tool 'when you want the newest routing' and that results are compared against the stable router. It does not explicitly state 'do not use when stability is required,' though the beta/experimental framing implies that exclusion.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds rich detail: refusal reasons, evidence quotes, exact response shape, and the guarantee to use only tool-retrieved content. This goes well beyond the structured metadata and matches 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 front-loaded and information-dense, with the core purpose and the key contrast with ask_pipeworx appearing first. It is slightly verbose in relaying routing internals and all refusal reason values, but every detail serves a real decision or invocation need.

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

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

With no output schema, the description fully specifies success and refusal return shapes, possible refusal reasons, and the tradeoff versus ask_pipeworx. Nothing an agent needs to invoke it correctly or interpret its result is missing.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds no parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a grounded, hallucination-resistant answer mode that extracts answers strictly from tool results, and distinguishes it from ask_pipeworx by its evidence and refusal behavior. It states the exact resource and action, so an agent can separate it from siblings without opening schemas.

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

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

It explicitly says when to use this tool ('whenever an answer will be quoted, cited, or acted on...') and provides a concrete alternative condition ('prefer ask_pipeworx for casual lookups'). It also notes the extra LLM call cost, which directly informs tool selection.

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

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

Annotations already indicate safe operations (readOnlyHint, idempotentHint). The description goes far beyond by detailing low-confidence resolution blocking, closed market handling, wide-spread liquidity warnings, resolution-rule risk parsing, and news fallback behaviors. 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 excessively long, containing multiple paragraphs of detailed examples and edge cases that could be in separate documentation. It lacks conciseness, though the first sentence effectively front-loads the purpose.

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

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

Given the absence of an output schema, the description compensates by fully explaining the response structure, including conditional fields, error states, and safety mechanisms. It covers all necessary context for an agent to understand the tool's behavior.

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

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

With 100% schema coverage, the description adds value by explaining the 'depth' parameter's enum values (quick vs thorough) and the 'include_raw' parameter's effect. This goes beyond what the schema provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input formats and output components. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, leaving some ambiguity.

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

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

The description gives explicit use cases ('Use for "should I bet on X"...') and describes what the tool does. It does not provide explicit when-not-to-use guidelines or mention alternatives, but the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorted results, citation URIs.

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 examples and front-loaded use cases. Could be slightly more concise, but all sentences earn their 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?

Covers key aspects: input types, output metrics, sorting, citation URIs, and efficiency claim. No output schema, but description compensates adequately. Missing error/pagination info, but not critical for this tool.

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

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

Schema coverage is 100%, so parameters are fully described. Description enriches by explaining what each type returns (metrics for company/drug) and how values are interpreted (tickers vs names), adding value beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, specifying exact metrics pulled per type. It distinguishes from siblings (e.g., entity_profile) by explicitly preferring over sequential single-pack lookups.

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

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

Provides explicit usage examples and states to prefer this tool over sequential lookups. Could mention alternatives like entity_profile for single entity, but sufficient for comparison context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description only adds directionality (in_area → out_area), which is partially inferable from parameter names. No details on data format, time resolution, or 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?

Extremely brief (one sentence). Not wasteful, but lacks substance. Could fit more useful information without becoming 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?

Despite rich annotations and presence of output schema, the description omits critical details about time period format, data units, or constraints. Agent may struggle to invoke correctly without additional schema inspection.

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 50% (period_start and period_end have no descriptions). The tool description does not clarify parameter formats or semantics. Examples in schema help but are not in the description.

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

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

Description clearly states the tool returns physical flow across an interconnector with direction (in_area → out_area). The verb is implied by 'flow' in context of a data tool, and it distinguishes from energy-related siblings by focusing on cross-border interconnector flow.

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

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

No guidance on when to use this tool versus alternatives. No mention of prerequisites or exclusions. Agent has no context for selection beyond the description.

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 context about hourly granularity and the specific data type (day-ahead auction prices), which is useful 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 extremely concise, only two sentences, with the key information front-loaded. Every word adds value without redundancy.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers the essential aspects: what data is returned, the unit, the time format, and the zone concept. It is nearly complete for a straightforward fetch operation.

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

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

Schema coverage is 100%, so the schema itself documents all three parameters. The description reinforces the format and adds 'bidding zone' context, which is already in the schema, providing marginal additional 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 provides day-ahead auction prices per hour for a bidding zone, with units and format specified. This distinguishes it from sibling tools like actual_generation_per_type or actual_load.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention conditions, exclusions, or comparisons with other energy tools.

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

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

Beyond the read-only and idempotent annotations, the description discloses account and plan requirements, latency ranges, parallel routing across 5,724 tools, the findings-packet structure, gaps[] behavior, contradictions[], hop fields, resolvable citation URIs, and semantic excerpting. It also warns that uncatalogued topics return mostly empty gaps, which is exactly the kind of behavioral nuance annotations cannot 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 long but densely informative; every sentence adds operational value, and the most decision-critical facts (account requirement, alternatives) are front-loaded. Given the tool's complexity, the length is appropriate rather than wasteful, with only minor overlap of the schema's depth descriptions.

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 no output schema, yet the description fully specifies inputs, outputs, failure behavior, authentication requirements, cost tiers, latency, and routing to sibling tools. An agent has everything it needs to decide whether to call this tool and to understand what to do with the result.

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

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

The input schema already covers both parameters in detail, so the baseline is 3. The description adds practical meaning by explaining what each depth level actually does operationally — gap recovery, lead-chasing, contradiction scanning — and clarifies that broad/multi-part natural language questions are 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 states a specific action and resource: grounded multi-source research across Pipeworx's 1,497 structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, and concrete example questions make the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, prefer ask_pipeworx for single lookups or breaking/current-news topics, and use ask_pipeworx if not signed in. It even names the alternative tools directly, leaving no ambiguity.

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

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

Annotations already indicate readOnly and idempotent. Description adds that results come with full schemas and examples, ready to call directly, which is useful behavioral context.

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

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

Description is concise, well-structured, front-loaded with purpose, and every sentence provides essential 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?

Despite no output schema, the description explains the return format (names, descriptions, schemas, examples) and lists covered domains, making it complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that multiple parameters are aliases for 'query' and mentioning the limit default, improving 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 finds tools by describing data or task, lists many domains, and specifies it returns top-N relevant tools with schemas, distinguishing it from specialized sibling tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set,' providing clear when-to-use guidance and suggesting it is for exploration before specific tasks.

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 and destructiveHint=false, and the description adds valuable context: it describes the multi-source fan-out, mentions soft-fail for patents, and details the returned fields. No contradictions.

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

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

The description is lengthy but every sentence adds value, with examples upfront. It could be slightly condensed, but it remains well-structured and informative.

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

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

Despite lacking an output schema, the description thoroughly explains the return structure (cik, filings, fundamentals, patents, news, LEI) and failure modes. For a complex tool with no output schema, this is remarkably complete.

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

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

Schema coverage is 100%, but the description adds meaning: it explains that type is limited to 'company' for now and that value expects a ticker or CIK, not a name, compensating for any ambiguity in the schema.

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

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

The description clearly states the tool's purpose: retrieving a comprehensive profile of a US public company from multiple sources in a single call. It provides many example queries and explicitly distinguishes from sibling tools like resolve_entity.

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

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

The description explicitly recommends preferring this tool over chaining single-source lookups and specifies when not to use it (e.g., for names, use resolve_entity first). This provides clear guidance on when to use versus alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about use cases but no extra behavioral details. Consistent, 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?

Two sentences with no wasted words. Front-loaded purpose, then usage guidance.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, usage, and parameter meaning. References siblings for context.

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

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

Schema coverage is 100% and describes 'key' as memory key. Description adds no additional semantics beyond schema.

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

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

Clear verb 'delete' with specific resource 'memory by key'. Distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Mentions 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context (fetches page, extracts key elements, emits markdown format) beyond what annotations provide, without contradicting them.

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

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

The description is concise: a single paragraph with four sentences. It front-loads the main purpose, then details, then use cases. No superfluous words or redundancy.

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

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

Given the simplicity (2 params, no output schema), the description sufficiently covers what the tool does and its output. It lacks details on error handling (e.g., unreachable URL) but is otherwise complete for a straightforward 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?

Schema coverage is 100%, so baseline is 3. The description reiterates the parameters (url, max_links) but does not add significant new meaning beyond the schema descriptions. No additional validation or format details are provided.

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

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

The description clearly states the tool generates an llms.txt file for a URL, with specific actions (fetches page, extracts title/description/key links) and output format. It distinguishes from siblings by listing explicit use cases (getting client site indexed, drafting own project, auditing competitor).

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 via 'Useful for:' but does not explicitly state when not to use the tool or mention alternative tools. However, the listed use cases give clear guidance on appropriate contexts.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety traits. The description adds no further behavioral context (e.g., data freshness, aggregation level). With annotations present, the bar is lower, but the description adds minimal value beyond what annotations and schema provide.

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

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

The description is a single sentence that immediately conveys the core purpose. It contains no unnecessary words and is efficiently front-loaded with the key information.

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

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

Given the tool's simplicity (2 params, output schema exists), the description is mostly sufficient. It mentions the key output dimension 'by production type'. However, it could briefly note that results are per the specified area and year, which is implied but not explicit.

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

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

The schema covers 100% of parameters with descriptions ('area' as bidding-zone EIC code, 'year' as numeric year). The description does not add any additional meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the tool returns 'year-end installed generation capacity by production type (MW).' It identifies the specific verb ('installed capacity') and resource ('by production type'), but does not distinguish it from the sibling tool 'actual_generation_per_type', which also involves generation capacity.

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

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

There is no guidance on when to use this tool versus alternatives like 'actual_generation_per_type'. The description lacks any context about when to use this tool or when not to, and no alternatives are mentioned.

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 as safe. The description adds value by specifying the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), providing detail 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 extremely concise—two sentences with no extraneous information. It is front-loaded with the core purpose and immediately useful.

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

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

For a simple listing tool with one optional parameter and no output schema, the description fully covers purpose, return format, and usage context. No information is missing.

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

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

The input schema has 100% coverage with one optional boolean parameter 'include_inactive' described in the schema. The tool description does not add any extra semantics beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and lists the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by being the listing tool.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It provides context on when to use the tool, 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?

With all annotations set to false, the description must carry the full burden of behavioral disclosure. It excels by detailing the claim_token workflow, rate limit (5 per identifier per day), cost (free, no quota), and how feedback is processed (daily digests, roadmap impact). It also advises against pasting end-user prompts. This is strong context, though it could mention the exact response format for a successful submission beyond the token.

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

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

The description is longer than average but front-loaded with the core purpose and usage, followed by crucial operational details. Every sentence earns its place: the scope limitation, claim_token mechanism, and rate limit are all essential for correct invocation. It is well-structured and free of fluff, though it could trim the motivational line about daily digests without losing utility.

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 provides a complete picture for a tool with no output schema: it explains what the tool does, when to use it, how to scope feedback, the claim_token return flow, rate limits, and quota impact. It adequately covers the workflow and expectations. It does not describe the exact response envelope, but the claim_token mention suffices for a feedback tool.

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

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

Schema description coverage is 100%, and each parameter already has a thorough description: the type enum explains each value, context clarifies its sub-fields, message describes content and length, and claim_token explains the read-back flow. The tool description adds a small extra by demonstrating claim_token usage inline, but the schema already carries the semantic weight. Baseline 3 for high coverage is appropriate.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback types (bug, feature/data_gap, praise) and explicitly scopes to tools served by this Pipeworx connection, distinguishing it from any sibling tools. This leaves no ambiguity about what the tool 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 explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well') and provides an alternative course of action for tools from other MCP servers ('file it with that server instead'). This is textbook usage guidance with clear exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds beyond these: data source ('CF analytics-engine'), no PII, caching behavior (5min-1h depending on window), and the nature of the data (aggregated calls). 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 paragraphs with bullet points for use cases. Every sentence adds value: purpose, use cases, data source, caching. No redundancy or 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?

Given no output schema, the description explains return values (top tools, top packs, call volume) and window options. It also covers data source, privacy, and caching. Could be more detailed on output format, but given low complexity (1 param, no nested objects), it is sufficient.

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

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

Schema coverage is 100% with one parameter (window) having an enum and description. The description adds value by explaining the trade-off between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides semantics beyond the schema's basic definition.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', specifying the verb (returns), resource (trending usage data), and scope (window selection). It distinguishes from sibling tools by focusing on aggregated usage of other AI agents, which is unique among siblings like 'entity_profile' or 'discover_tools'.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case with agent demand). It implies when to use but does not specify alternatives or when not to use. However, the context is clear enough for an AI agent to decide.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive hints, which are consistent with the description. The description adds extensive behavioral details including monotonicity checks, partition-sum logic, semantic anchor constraints, placeholders filter, and fill check mechanics, far exceeding 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 relatively long but all information is relevant and valuable. It is front-loaded with the core purpose. A slight reduction in technical detail could improve conciseness, but it remains 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?

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities array, partition_check object with fields like gap_pp, suggested_trade, reasoning) and the fill check mechanism. It also mentions custom sizing via another tool, ensuring the agent understands both outputs and limitations.

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, but the description adds significant meaning: 'event' accepts slugs or full URLs, 'topic' uses seed questions, and explains the behavior of each mode in detail, going well beyond the schema.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, clearly differentiating three modes (trending scan, event-specific, cross-event). This is specific and distinguishes it from sibling tools like polymarket_edges or 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?

The description provides explicit guidance on when to use each mode: call with no args for trending scan, use 'event' for a specific market slug, and 'topic' for cross-event scanning. It also warns against trading when realizable_edge_pp ≤ 0, indicating when not to use the output.

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

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

Annotations (readOnlyHint, idempotentHint) are already provided, but the description adds significant behavioral detail: model families, segments, caching (1h KV-level), edge calculation with slippage, diagnostics, and 24h-move warning. 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 very detailed but somewhat verbose, containing multiple paragraphs and technical jargon. It is front-loaded with purpose but could be more concise. However, the structure with segments and lists aids readability.

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

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

Given no output schema, the description comprehensively explains the response structure (by_segment, diagnostics, fed_candidates) and derived fields (edge_pp_net, kelly_fraction, etc.), providing sufficient context for an agent to interpret results.

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

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

All 9 parameters are described in the schema (100% coverage), and the description adds further context for parameters like min_kelly, slippage_pp, min_partition_leg_kelly, explaining their practical effect and recommended values.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb (scan/return) and resource (opportunities), and distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection from disagreement.

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

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

The description explicitly says it is 'Built for "what should I bet on today"' and mentions tradeable-edge knobs and filter usage. While it doesn't explicitly state when not to use or compare with siblings, the use case is clear and implied.

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 it read-only and idempotent. The description adds rich details: response structure (tracked, expired, snapshot_dates), time-series behavior, and limits (60-day TTL, non-intraday decay). No contradictions.

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

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

The description is well-structured and front-loaded but somewhat verbose. It includes necessary details without redundancy, earning a slightly above-average score.

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

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

Given no output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) and limits. It covers all aspects needed 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%, so baseline is 3. The description repeats the same parameter info (days, window) without adding new 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 purpose: tracking edge persistence and decay from daily snapshots. It distinguishes from siblings like 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?

The description provides implicit usage context by contrasting fresh vs. old edges, aiding when to use. However, it lacks explicit comparison to alternative tools like polymarket_edges or polymarket_arbitrage.

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

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

Annotations indicate safe, idempotent, read-only behavior. Description adds significant behavioral context: walks the ladder, returns a verdict (clean/degraded/cannot_fill), identifies thin legs, and warns about forced directional risk. No contradiction with annotations.

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

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

Description is well-organized into sections (single-market, basket, usage advice). Every sentence contributes value, though slightly verbose in listing all return fields. Still effective and efficient.

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

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

Despite no output schema, the description thoroughly enumerates all return values, explains two modes, and covers edge cases like thin legs and forced directional risk. Provides essential context for a complex analytical tool.

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

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

Schema covers all 4 parameters with descriptions. The tool description enriches semantics by explaining default values for size_usd and side, the auto-derivation of basket side from partition sum, and the interpretation of size_usd for buys vs sells.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It lists specific return fields and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises using this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about risks of partial fills and unhedged positions, 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?

Even with readOnlyHint/idempotentHint/destructiveHint already declaring this a safe read operation, the description adds substantial behavioral context: the compatibility_warning/compatibility_codes mechanism and the explicit instruction to 'read them even when matched_pairs>0,' the machine-readable code list, and — most valuably — the clarification that 'temporal_alignment_unknown... is NOT the same as confirmed-aligned' and that 'null means it could not be computed, not that the two sides align.' The fees_note (gross spread, not net tradeable edge) and the skipped_unclassified counters further disclose interpretation pitfalls. 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 exceptionally dense with useful information and every sentence has earned its place — there is no filler and the purpose is front-loaded in sentence one. However, it is a single unbroken wall of text (~600+ words) with no paragraph breaks, bullets, or headers separating modes, safety fields, codes, temporal logic, fees, and skipped counters. For a tool this complex, the lack of any structural scaffolding materially hurts scannability, so despite zero padding it reads as under-structured rather than 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 the tool's real complexity — 3 params in 2 modes, an extensive compatibility-code taxonomy, temporal-alignment semantics, fee caveats, and skipped-pair counters — and that there is NO output schema, this description carries the full burden of explaining return values and edge cases. It covers the response shape (leg-by-leg prices, top_spreads_pp, Kalshi − Polymarket sign convention), the per-entry flags[], the never-paired 'unknown' leg rule, the temporal_alignment object, and the gross-vs-net fee limitation. Nothing an agent needs to interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the mode interaction: that `kalshi_event_ticker` and `polymarket_event_slug` 'Override the topic-mapped side' — an override relationship not stated in the isolated schema parameter descriptions. It also describes the topic→event auto-fetch behavior. The topic enum values are duplicated from the schema rather than newly explained, which keeps this from a 5, but the override semantics and mode-combination logic are genuinely additive.

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 first sentence states the exact resource and operation: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further quantifies the signal (2-25pp apart) and names the scope boundary ('for the same resolving question'). The cross-venue, two-specific-venues nature clearly separates it from the single-venue siblings like polymarket_arbitrage, polymarket_edges, and polymarket_edge_tracker, even without naming them. Verb, resource, and scope are all unambiguous.

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

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

The description explicitly documents TWO MODES and how to select between them: `topic` shortcuts auto-fetch mapped events, while explicit `kalshi_event_ticker` + `polymarket_event_slug` allow custom pairings, noting both run the identical matcher. It also sets expectations for reliability: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' The only gap is that it never names sibling alternatives (e.g., polymarket_arbitrage) or gives explicit when-to-use-this-vs-that exclusion rules, so routing is by content rather than by explicit comparison.

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 scoping details (IP, key hash, account) and behavior on omitted key, exceeding annotation content.

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

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

Four concise sentences, front-loaded with purpose, followed by use cases, scoping, and pairing. Every sentence adds value, 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?

For a simple retrieval tool with one optional parameter and no output schema, the description covers retrieval, listing, scope, and associated 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 adds meaning by explaining the effect of omitting key (list all keys) and provides usage examples, 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?

The description explicitly states 'Retrieve a value previously saved via remember, or list all saved keys', using specific verb-resource pair and distinguishes from remember and forget 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?

Provides clear use cases (look up context without re-deriving) and mentions scoping and pairing with remember/forget, but does not explicitly state when not to use or compare to other 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 idempotent, read-only, non-destructive behavior. The description adds context about return fields (source, citation_uri, payload), the persistence of read flags via mark_read, and that polling is safe. This goes beyond annotations without contradiction.

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

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

Three sentences deliver purpose, key parameters, and an alternative access method without redundancy. The structure is front-loaded with the main action. Minor extra detail about the GET endpoint could be omitted but does not detract.

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

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

Given the absence of an output schema, the description covers return fields, filtering, and side effects (mark_read). It mentions polling but not pagination or limit behavior beyond schema. Overall sufficient for a tool with 5 optional parameters and rich 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining filter usage ('e.g. sec_8k'), clarifying that 'since' expects an ISO timestamp, and describing the effect of 'mark_read' on subsequent calls. This enriches 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 pulls fired events from a subscription feed, using specific verbs like 'Pull' and resource 'subscription feed'. However, it does not explicitly differentiate from sibling tools such as 'subscribe' or 'list_subscriptions', leaving some ambiguity.

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

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

The description mentions polling works fine and provides filtering examples (type, since), implying typical usage. But it lacks explicit guidance on when not to use this tool or when to choose alternatives like 'list_subscriptions' or the GET endpoint. No conditions or limitations are stated.

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

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

The description adds significant behavioral context beyond annotations: it reveals parallel fan-out to multiple APIs, fallback logic, soft-fail for USPTO, and return structure (changes[] grouped by source). This fully informs the agent of the tool's behavior.

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

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

The description is well-organized: begins with example queries, then explains the tool's behavior, parameter details, return format, and alternative tool. While slightly verbose, every sentence adds value and there is no extraneous information.

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

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

Given the tool's complexity, no output schema, and multiple data sources, the description covers all essential aspects: acceptable inputs, data sources, fallback behavior, return format, and relationship to sibling tool. It is complete enough for confident tool selection.

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

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

The input schema already describes all parameters (100% coverage), but the description adds valuable semantics: examples of 'since' formats (ISO date and relative shorthand with monitoring suggestion), clarification that 'value' accepts ticker or CIK, and guidance to use '30d' or '1m' for typical monitoring.

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 change feed for a company over a specified time window, aggregating SEC, GDELT/GNews, and USPTO data in one parallel call. It also distinguishes itself from the sibling 'entity_profile' tool by specifying when to use the alternative.

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

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

The description provides explicit example queries ('What's new with X', 'latest on Y') and explains when to use the sibling 'entity_profile' instead. It details fallback behavior (GDELT->GNews) and acceptable input formats, but does not explicitly list scenarios where the tool should not be used.

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 idempotentHint=true and non-destructive. The description adds further context: scoping by identifier, persistence differences between authenticated and anonymous users, and 24-hour retention for anonymous sessions.

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

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

Three sentences, front-loaded with purpose, no fluff. Every sentence adds value: purpose, usage, and behavioral 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?

Considering the tool's simplicity (2 required params, no output schema), the description covers all necessary aspects: what it does, when to use, how it works, and lifetime behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no further semantics beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool saves data for later reuse, using specific verbs ('save', 'store') and specifies the resource (key-value pair). It distinguishes itself from siblings like 'recall' and 'forget'.

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

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

The description explicitly says 'Use when you discover something worth carrying forward... so you don't have to look it up again' and suggests pairing with 'recall' and 'forget', providing clear usage context.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds substantial non-obvious behavior: graceful degradation when GLEIF/OpenFIGI are unavailable, the cascade of internal lookups ('replaces 2-3 manual lookups'), the explicit `unresolved` field for failed identifiers, source labelling, and the ambiguity rule for multiple FIGI matches. This exceeds what annotations communicate and meaningfully shapes agent expectations.

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

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

The description is long but every clause earns its place — it packs in edge cases, fallbacks, and output expectations that would otherwise require probing. It front-loads the core purpose and the critical 'Use FIRST' instruction. Minor redundancy exists (e.g., both inline parentheticals and a dedicated SUPPORTED TYPES block), but it remains efficient for the amount of specificity conveyed.

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

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

For a tool with two parameters, multiple data sources, and no output schema, the description covers all necessary call-time decisions: input format, edge cases (bonds, non-US issuers, ambiguity), fallback behavior, and what the response will contain (labelled identifiers, unresolved list, figi_candidates). Nothing an agent needs to invoke this correctly is missing.

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

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

Though schema coverage is 100%, the description dramatically enriches parameter meaning. For `type` it distinguishes 'company' and 'drug' with concrete sub-behaviors. For `value` it gives format examples (AAPL, CIK, ISIN, 'ozempic'), warns against including security-class words on bond issuer names, and explains how ISINs map to legal entities. This is the single most valuable area of the 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 opens with a concrete verb and resource ('resolve a user-spoken NAME to the canonical/official identifiers'), immediately distinguishing it from sibling profile or comparison tools. It explicitly enumerates supported types (company, drug) and the identifier sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), and gives realistic query examples. This is far beyond a tautology.

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

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

The description states 'Use FIRST whenever you have a name but need an ID' — a clear, actionable trigger. It also explains scope boundaries (e.g., non-equity instruments resolve, ISINs resolve to legal entities, ambiguous matches return figi_candidates). However, it does not explicitly name alternative tools to switch to when this one is inappropriate, so it stops short of a full exclusionary frame.

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 readOnly, openWorld, idempotent, non-destructive. Description adds that it internally calls ai_visibility_check, returns ranked list with score/confidence/signal density, and treats first entity as subject. No contradictions; adds meaningful 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?

Three sentences, front-loaded with the core purpose, each sentence adds unique value (comparison, method, use case, return format). No redundancy or 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?

Despite no output schema, the description adequately explains return fields (score, confidence, signal density per entity) and entity range (2-8). Covers complexity of probing multiple models and ordering logic.

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

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

Schema coverage is 100% with descriptions. The description adds the important nuance that the first entity is the 'subject' for narrative and that models and _apiKey are related. This extra semantic information is valuable.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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 use for competitive AI-marketing audits and provides a concrete question. While it doesn't mention when not to use or alternatives, the context is clear and sufficient for appropriate 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, open-world, and non-destructive. The description adds significant behavioral context: fans out to multiple services, partial failures degrade gracefully, first measurement can take 5-30s, sources_failed listed on timeout. 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 moderately long but front-loaded with the core purpose. Every sentence adds value, covering purpose, use cases, return info, limitations, and error handling. Could be slightly more structured but effective.

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

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

Despite no output schema, the description details the return summary block and lists fields. It explains behavior, limitations, partial failures, and ecosystem scope. Comprehensive for a two-parameter composite tool.

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

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

Schema coverage is 100% and descriptions are already clear. The description repeats some schema info (scoped packages, version defaults) but does not add new meaning beyond what the schema provides. 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 it is a composite check for deciding whether to add an npm package, covering license, advisories, bundle size, etc. It explicitly distinguishes from siblings by naming specific use cases and ecosystem scope.

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

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

Explicitly says 'Use whenever an agent asks...' and lists the questions it answers. Provides ecosystem limitation (NPM only) and notes that other ecosystems use deps.dev directly. Lacks explicit when-not-to-use but context is clear.

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

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

Discloses embedding model (BGE-base-en), windowing (500-char overlapping), similarity metric (cosine), character cap (200K) with truncation and flagging, and output details (passages with offsets and scores). Adds significant 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?

Four sentences, front-loaded with main idea, each sentence adds unique information (purpose, use case, behavior, constraints, pairing). 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?

For a tool with 3 parameters and no output schema, the description covers input format, processing details, output structure, constraints, and integration with a sibling tool. Sufficient 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%; description repeats the text max (~200K chars) but adds workflow context (e.g., 'the text you already pulled', 'natural-language query') and links parameters to the output (top-N passages with offsets and scores). Provides moderate additional meaning.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article, long tool result). Distinguishes from siblings by describing pairing with ask_pipeworx_grounded and the inside-a-record use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded for grounding over relevant passages, providing clear when-to-use and alternative workflow.

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

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

Annotations indicate idempotentHint=true, but the description says 'Returns the new subscription id,' implying each call creates a new subscription, which could contradict idempotency. However, the description does not explicitly address idempotency or deduplication. It adds extensive behavioral details: authentication requirement, type-specific parameters, delivery channel nuances (SMS cap, webhook auto-disable, signing). The contradiction is mild, but the description could be more transparent about the idempotency model.

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 fairly long but well-structured: purpose first, then requirements, supported types, delivery options. Every sentence adds value—no fluff. It could be slightly more concise by grouping common patterns, but the clarity gained from the detailed examples justifies the length. It is front-loaded with the core purpose.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers prerequisites, valid parameter combinations, delivery channel constraints, and return value (subscription id). It does not cover error cases or output schema (not needed). For an agent to correctly invoke this tool, all necessary information is present.

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 significant meaning beyond the schema's brief descriptions. For each type (sec_8k, polymarket_edge, etc.), it provides concrete parameter examples and notes like 'items:["5.02"] = officer change.' For delivery, it details webhook signing and failure auto-disable. This far exceeds what the schema alone conveys.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb (create) and resource (subscription to event stream). The title 'Subscribe to Alerts' further reinforces this. It distinguishes from sibling tools like list_subscriptions and unsubscribe by implying creation vs listing/removal.

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

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

The description provides explicit guidance on when to use the tool (to set up monitoring) and requirements (Pipeworx OAuth account). It details supported subscription types and their parameters, delivery channels, and links to alternatives like recent_alerts or the registry endpoint. It implicitly advises when not to use it (e.g., anonymous users cannot persist subscriptions).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds behavioral context: it returns category-bucketed examples drawn from a live catalog, and is non-destructive (onboarding). There is no contradiction; the description complements annotations well.

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 typical user queries and efficiently conveys purpose, usage, and return structure. Every sentence is informative, though slightly verbose with repeated examples ('company financials, drugs & clinical trials...'). Still well-structured and not wasteful.

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

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

Given no output schema, the description adequately explains the return value (category-bucketed example questions with tool and argument shape). It also orients the tool within the sibling list by mentioning meta-tools and positioning it as the entry point. Complete for its role.

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 parameter 'topic'. The description adds meaning by listing example values (finance, pharma, etc.) and explaining behavior when omitted (full spread). This goes 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's purpose as the onboarding entry point for a new agent, returning category-bucketed example questions with tool and argument shapes. It uses specific verbs ('returns', 'call') and distinguishes itself from sibling tools like ask_pipeworx or compare_entities by explicitly mentioning meta-tools and the 'what can I ask' use case.

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

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

The description explicitly says to use this tool FIRST when you don't know what Pipeworx can do, or to learn how to call meta-tools. It also explains how to use the optional 'topic' parameter to focus. It lacks explicit when-not-to-use instructions but gives strong positive 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?

The description discloses that the row is deactivated (not deleted) and that historical events stay available via recent_alerts, which goes beyond annotations. 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 two concise sentences, front-loaded with the main action, with 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?

For a simple tool with one parameter and no output schema, the description fully explains the behavior, ownership constraint, and side effects.

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

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

Schema coverage is 100%, and the description only repeats the parameter purpose (by id). It adds no new semantic meaning beyond the schema.

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

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

The description starts with 'Cancel a subscription by id,' clearly stating the verb (Cancel) and resource (subscription). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' through the action of cancellation.

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

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

It explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on when to use. However, it does not explicitly mention alternatives or when not to use.

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

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

Provides rich behavioral detail beyond the annotations: distinguishes between structured SEC EDGAR/XBRL path and grounded fallback, enumerates the six verdicts, and warns that could_not_verify means the check did not happen and must not be treated as evidence. This goes far beyond readOnly/opensWorld/idempotent flags and gives essential caller guidance.

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

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

Although the description is long, every sentence adds distinct value: trigger phrases, usage scope, routing logic, verdict list, caller warnings, and the efficiency benefit. It is front-loaded with the most important information and avoids 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 complex verification tool with no output schema, the description fully explains the return format (verdict, value, citation, reasoning), the two processing paths, error semantics, and the difference between unsupported and could_not_verify. This gives an agent everything needed to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100% and already documents both claim and tolerance_pct with examples. The description adds high-level context about percent-delta math and tolerance behavior, but it does not meaningfully extend what the schema already says about the parameters.

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

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

The description opens with explicit trigger phrases ("Is it true that…", "fact check", "verify the claim that…") and states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes the tool from siblings by framing it as a structured verification engine that returns a verdict, not just an answer.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and contrasts company-financial claims with any other factual claim, routing each to the proper pipeline. It does not name specific sibling tools as alternatives, but it explains that it replaces 4–6 sequential calls, which gives clear usage context.

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